Our support site has moved to https://support.intuiface.com

Call a POST/PUT request using a REST Web Service

Table of Contents

    Introduction

    NOTE: With IntuiFace API Explorer, there is no need to hand-craft your own interface asset for a REST-based Web Service. This article presents the manual creation process, a process that should typically be unnecessary.

    This article assumes you have already reviewed and understand the article Design an Interface Asset Descriptor for a REST-based Web Service

    To illustrate how to write the descriptor for a PUT/POST request, we are going to use the Google URL Shortener API. You can download the completed interface descriptor here and a sample IntuiFace project using this interface here.

    General Properties

    The general properties section of this descriptor is written just as described in the previous article.

    {
     "kind": "discovery#restDescription", 
     "discoveryVersion": "v1",
     "id": "urlshortener:v1",
     "name": "urlshortener-light",
     "version": "v1",
     "title": "URL Shortener Light",
     "description": "Lets you create goo.gl short URLs",
     "documentationLink": "http://code.google.com/apis/urlshortener/v1/getting_started.html",
     "protocol": "rest",
     "baseUrl": "https://www.googleapis.com/urlshortener/v1/",
     "basePath": "/urlshortener/v1/",
     "rootUrl": "https://www.googleapis.com/",
     "servicePath": "urlshortener/v1/", 
    ...
    

    Schemas

    The only schema used in this sample is the Url object, as described in Google's documentation here

    We will only keep the 3 properties we need for our use case:

    • id: the Short URL returned by the insert method
    • kind: a mandatory parameter set with the fixed string "urlshortener#url"
    • longUrl: the URL to shorten

    Documentation about creating schemas can also be found in the same article mentioned previously.

    "Url": {
       "id": "Url",
       "type": "object",
       "properties": {    
        "id": {
         "type": "string",
         "title": "Short URL",
         "description": "Short URL, e.g. \"http://goo.gl/l6MS\"."
        },
        "kind": {
         "type": "string",
         "description": "The fixed string \"urlshortener#url\".",
         "default": "urlshortener#url"
        },
        "longUrl": {
         "type": "string",
         "title": "Long URL",
         "description": "Long URL, e.g. \"http://www.google.com/\".
        }   
       }
    }
    

    Resources & Methods

    Since we are going to use a POST method, the Interface Asset is going to be the resource itself and not the methods. The differences with the example in the previous article are as follows:

    • methods of the resource will be seen as Actions of your Interface Asset in Composer
    • methods won't be called automatically when loading the experience, so you will have to call them explicitly with a Trigger/Action couple (ex: in response to the Button Released trigger)
    • response to the request will be stored in the Properties of the Interface Asset. To visualize it in a Text asset, for example, you would bind the Text property to the URL Shortener Interface Asset property (see below)
    "resources": {
      "url": {
      "isInterfaceAsset": true,
      "title": "URL Shortener",
       "methods": {    
        "insert": {
         "id": "urlshortener.url.insert",
         "path": "url",
         "title": "Shorten URL",
         "httpMethod": "POST",
         "description": "Creates a new short URL.",
         "request": {
          "$ref": "Url"
         },
         "response": {
          "$ref": "Url"
         },
         "scopes": [
          "https://www.googleapis.com/auth/urlshortener"
         ]
        }   
      }
     }
    }
    

    Call your POST request from Composer

    How to call the action in Composer:

    URLShortener-Action.jpg

    How to retrieve the response and bind an asset property to the URL Shortener property:

    URLShortener-Binding.jpg