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.
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:
How to retrieve the response and bind an asset property to the URL Shortener property:
Comments
0 comments
Article is closed for comments.