Before proceeding, be sure to review Interface
Asset general concepts and our introduction to creating
your own interface asset. Treat these articles as prerequisites
to the content below.
Introduction
An Interface
Asset using the REST protocol only needs a descriptor
file with a .ifd extension to be used in
IntuiFace. No dll or other files are required. Here we explain step
by step how to describe a REST-based API.
Once you have created this .ifd (IntuiFace Descriptor) file:
create a folder with your Web Service name and copy the .ifd
inside it
copy this folder to
C:/Users/{UserName}/Documents/IntuiFace/Interface
Assets/ and then restart Composer. By doing so your
Interface Asset will become available in the
Select an interface panel (see image below) across
all of your projects.
If your new interface does not appear in Composer, check
Composer's log file:
C:\ProgramData\IntuiLab\IntuiFace5\Composer\Logs\Trace.log.
This file contains useful information that may help you
troubleshoot the formatting of your ifd file.
In this article, we will use the Rotten Tomatoes REST
API, a freely accessible provider of movie information.
You can
download the descriptor we are using as a sample for this
article.
Useful tools
IntuiFace's interface descriptor files use the JSON (JavaScript Object Notation) data
interchange format. Here are links to some excellent tools that
will help to ensure the consistency of your JSON-based descriptor
files:
to edit your .ifd (JSON) file
online: JSON Editor
Online
locally, you can use Notepad++
to generate JSON schemas: http://jsonschema.net/
NOTE: Be sure to deselect "Force required" in the
General parameters section. It adds an unnecessary
field to your schema.
to check if your .ifd file is valid: http://jsonlint.com/
to monitor the data going in & out of your
computer: Fiddler
if your API doesn't provide dynamic documentation like
RottenTomatoes, we recommend you use the Postman HTTP client to test your
services
NOTE: Never edit your .ifd files while Composer
is running. If you wish to make changes to a .ifd file, exit out of
Composer first.
Process for creating an IntuiFace Descriptor File for your REST
Web Service
Here is the overall process we recommend when you want to create
your own Interface Descriptor for a REST Web Service:
In your prefered editor, prepare a skeleton of the
descriptor containing the sections described below
(General Properties, Schemas, Resources & Methods). For a quick
start, copy-and-paste an existing descriptor, delete the unwanted
content and replace the mandatory properties.
Using your Web Service API documentation & JSON Schema, generate the
schemas of the response objects you will have to
manipulate.
Update the Resources & Methods section in
your editor. Don't forget to add the "isInterfaceAsset" =
true property in the proper place (explained later in this
article)
Validate your descriptor using JSONLint
Copy your descriptor file to
C:/Users/{UserName}/Documents/IntuiFace/Interface
Assets/{YourServiceName}/ to test it
General properties of
the descriptor
First, we need to specify the overall properties of the API,
including its name, description, used protocol and base URLs for
REST requests.
Protocol: this property defines the type of
response awaited from the Web Service. It can be
rest or rest_json: if the Web
Service answers with JSON content
rest_xml: if the Web Service answers with XML
content.
We have added a requestDelay property to avoid
sending too many requests to the Web service. You can change or
remove this value depending on the limitations of your API.
In many cases, APIs have common parameters used across all
requests, like an API key to identify the user of the service. This
type of parameter is added to the parameters
section of the descriptor:
The apiKey parameter is required for every
request, so "required" is set to true. In IntuiFace, a request can
be sent only if all of its required parameters have a value.
The "hidden" property prevents the display of a parameter and
its value in Composer's Properties panel.
Notes
If your Web Service requires “alt=json” as a
parameter, add it to the global parameters of the descriptor. It
will be applied to all of the methods you are going to define
below.
By default, the body of a Web Service request will be
compressed. If your service provider doesn’t
support body compression, add
"If.zipCompression" = false in the general
properties of your interface asset. (e.g.: Philips Hue)
Defining
Schemas
We can now describe data types. Types are
listed in the schemas section of the ifd file.
First, let's examine the JSON body structure returned by the Rotten
Tomatoes service named BoxOffice:
We have to create a schema associated with this structure,
identifying all of the properties we want to be accessible in
Composer. For each property, you need to indicate its type, title,
description (and other properties if needed). See below for how a
Movie is described in the ifd file:
Don't worry, you don't have to write this on your own. You can
use JSON Schema to help you.
Copy your JSON body into the right panel and click Generate
Schema. In the Review tab you will find
the result to copy into your .ifd file.
Services may return a list of Movie instances. In this case, you
must add to the schema an array that handles a list of
movies:
All supported types and formats are listed in the
Google Discovery documentation
Important hints
Be careful: when asking a Web Service to return a list of
objects, you may have two different kinds of answers
if the result starts with a {, you have an
object which will probably have a property of type
array (like in our example above, the response is
an object with a movies array property)
if the result starts with a [, you have the
array itself as a response. In our previous
sample, we would have written it like this:
Warning: JSON Schema may confuse an array with a big object
containing a lot of properties
Appropriate values for $ref vs. type
$ref references an object schema, define in
the same descriptor in the schemas section
type denotes a basic type (**number, string,
bool, etc...**) including any and
null
Defining Resources &
Methods
We have just described the data structure. Now
we have to describe the services (aka. methods).
This is done in the resources section of the file.
We will use two services from the Rotten Tomatoes API : Box
Office and Movies Info.
More info about Resources & Schemas on
Google Discovery documentation
Box Office is an http GET method with two parameters: country
and limit.
The main parameter apiKey will automatically be applied as
described above in the parameters section of the
descriptor.
Here is what the request would look like if called in a Web
browser: http://api.rottentomatoes.com/api/public/v1.0/lists/movies/box_office.json?limit=16&country=us&apikey=******************
The path of the method is very important. It is
combined with the baseUrl property (see the
beginning of the descriptor file as described above) to form the
final URL of the request.
The isInterfaceAsset property value for this
method is set to true. This means it will be available in
IntuiFace Composer in the Interface Assets panel. The API can now
be used as an Asset. Its parameters will be displayed as asset
properties and when the value of those properties change, the REST
service is called.
Basic rule for the
isInterfaceAsset property
for a GET, set "isInterfaceAsset" = true as a
property of the method
for a PUT/POST, set "isInterfaceAsset" = true
for the resource.
See this article for more details.
This second example has a parameter named id
which is part of the URL of the request (and not an argument of the
query). Thus the path parameter includes the
variable id - movies/{id}.json - and the
location for the id parameter is
set to "path" instead of
"query".
If you want more information about resources/methods, here is
the
Google documentation
We have now generated an Interface Asset that can be added to
any IntuiFace Experience. Remember, copy your new ifd file to
C:/Users/{UserName}/Documents/IntuiFace/Interface
Assets/{YourServiceName}.
Sample descriptors
The following are references to REST-based Interface Assets
created by IntuiLab and used either in Composer or in some of
our
samples. Don't hesitate to use them as a starting point to
create your own!
Weather, directly available in Composer
Rotten Tomato (light), used in the
TicketBooking demo
If you have some cool REST Web Services to share, please
start a discussion to submit
them!