Introduction

Not familiar with the concept of Web APIs or need some help constructing a request URL? Start by jumping over to this article for a primer.

An API - Application Programming Interface - is the doorway produced by one piece of software so that other software programs can talk to it. Thanks to cloud computing, the most common API language these days is known as "REST-based Web Services".

Intuiface API Explorer enables the no-coding creation of an interface asset for any REST-based Web Services query. With this interface asset, a running Intuiface experience can dynamically read from and write to the data source and/or device accessible via that Web Service.

For anyone, of any skill set, API Explorer opens the door to tens of thousands of public and private APIs available in the cloud. There is everything from movie listings and weather forecasts to currency conversion, the latest photos from NASA, and all those connected objects among the Internet of Things. The majority are free to use - for example, check out the Programmable Web directory - while others may require an access fee. Some may be private and internal to your organization. Regardless, all are accessible in Intuiface.

Key Features

• Supports entry of any request URL or curl statement; accepts the contents of any XML, JSON, or raw text response.
• Uses a machine learning engine to identify the appropriate type for each result value and which results to preselect for visualization in Intuiface.
• Automatically generates an interface asset for the specified API call and creates a visualization of specified properties with an Intuiface experience.
• Enables the automatic display of multi-page results in a single view, avoiding the need to manually page through results within a running Intuiface experience.
• Permits on-the-fly modification of host, endpoint, and parameters to tailor the query for specific needs

NOTE: It is possible to hand-craft an interface asset for a REST-based Web Service, a topic discussed here. However, as you'll discover, it is far easier to use API Explorer, and the process is accessible to anyone of any skill set, not just developers.

Supported protocols

API Explorer can:

• submit both request URLs and curl statements.
• process GET, POST, PUT, PATCH, and DELETE requests.
  • a POST, PUT, PATCH, and DELETE request can have a body parameter. It will be sent in a JSON object with the following format: {"parameter name": value}.
• consume XML, JSON, or plain text formatted responses. This includes blog feeds, as those feeds are formatted using XML.
• work with gzip and deflate compression methods

How it works

Specifying your request URL or cURL statement

• Launch API Explorer while in Composer's Edit Mode. You must be actively editing an experience to run API Explorer.
  
• Enter your request URL or curl statement and submit it.
  
• Review the results. You can
  • change the property type for a value to ensure Intuiface properly represents it visually
    
  • change/add/remove parameter values within your request URL or curl statement and resubmit them
    
• Select the property values you wish to display in your experience. All property values will be accessible in Composer. You're selecting those properties you wish Composer to display.
  
• Click the "Create an interface asset" button.
  
• Assign a name to the interface asset you're about to create and a name for the IA category within which this new IA should be placed. Then click the "Create" button.
  
• You're returned to Composer. A visualization of the selected properties is automatically displayed in the scene you were editing, while an interface asset appears in the Interface Assets panel.
  
• If, at any time, you wish to revise your query, right-click your IA in the Interface Assets panel and select the Edit in API Explorer option.
  

Machine learning engine

API Explorer incorporates a machine-learning engine to help you decide which properties would be most appropriate for display within Intuiface. This engine monitors all queries entered by all Intuiface users around the world to improve its ability to:

1. Identify the type of value represented by a given property.
   In this example, note how API Explorer guessed that the "Price" property was of the type Quantity.
   
   You understand that this value is really of the type Currency, so you change it.
   
   The machine learning engine will note this and how, around the world, Intuiface users are setting "Price" to the type Currency. Eventually, API Explorer will learn to set "Price" to the Currency type automatically.
2. Preselect properties considered most likely to be interesting for visualization.
   In this example, note how API Explorer decided not to preselect the "Description" property for visualization (i.e. it's missing a checkmark).
   
   If you select the "Description" field for visualization, and around the world, Intuiface users are select the property "Description" for visualization - selecting it for any Web Service, not just this particular query - API Explorer will learn to preselect the "Description" field for visualization automatically.

NOTE: IntuiLab SAS, Intuiface, and API Explorer respect user privacy and never share entered information with anyone. The machine learning engine uses user selections to improve the assistance it provides.

Modifying your query

To the left of the Results panel is a breakdown of your request URL or curl statement into its constituent parts: host, endpoint, and parameters. Much can be configured here.

1. Each value is color-coded. You can match the colored bar to the left of each value with a part of the full statement listed above.
   
2. Hover your mouse over any of these values and it will be highlighted in the full statement above. In the following image, the mouse is hovering over the value "London" for the parameter "area"
   
3. Highlight any part of the Host or Endpoint then click the + button to convert the highlighted content into a new parameter.
   
4. Updating any of the host, endpoint, and parameter values will cause - once mouse focus leaves the modified field - API Explorer to run the now modified Web Services request and update the Results panel.
5. Parameter values can be toggled between representations as query or header parameters. Click the corresponding H or Q symbol to open the dialog, enabling you to make this change.
   
6. Parameter values can also be tagged as representing collection pagination parameters - i.e. indication of item offset, page offset, or item count per page as well as the applicable list if more than one exists in the results - when the request response is separated across multiple pages. With this information, Intuiface can automatically combine multiple pages into a single view within a running experience.
   

Create a JSON body for your request

Some web services using a POST, PUT, PATCH, or DELETE verb will require you to pass parameters in a JSON body. To create such a body, you must add one body parameter per key in the JSON. The parameter name will be the path to that key in the JSON object, using a dot as a hierarchy separator.

Let's take the example of the following body:

{ "product": 
   {
      "name": "BJURSTA",
      "size": {
         "width": 140,
         "height": 90,
         "depth": 75
      },
      "price": "99€"
   }
}

The parameters to add in the API Explorer will be the following. You can then change each of these parameters in a property of the generated Interface asset through its associated action.

Sharing results and the standalone API Explorer

API Explorer enables the creation of a shareable link containing all host, endpoint, and parameter values. Entry of this URL in any Web browser will open a standalone instance of API Explorer and display the Results view.

The shared view will not reflect modifications to property types or selected properties. The machine learning engine will apply its own decision-making.

The standalone API Explorer

• Can be used to research any request URL or curl statement. It is not limited to shared queries
• Creates an ifd file, the file used - under the covers - to represent an interface asset.
  

Properties, Triggers & Actions

Properties

Triggers

Actions

Result processing

Sometimes, the API responses will not give you the information you need in the correct or complete form, and you may need to process it before using it in Intuiface. An example is the Google YouTube Data API and its Search web service that only returns a videoId for each video result instead of a complete URL. See the picture below.

In this case, you can use a Value Converter to modify this value before using it in a property or an action parameter.
In the YouTube example above, we would use the Concatenate - Text Manipulation converter to build the proper URL using the video ID as the binding input.

Limitations

• API Explorer only supports Basic or Bearer authentication. It does not yet support Digest or OAuth2 authentication.
  • Exception: if the OAuth is a password grant type, this can be achieved with two different calls in the API Explorer. 
• It is not possible for multiple instances of Composer running on the same PC to each independently use API Explorer. You must close the first instance of Composer to use API Explorer before you can open API Explorer from another Composer instance.
• It is not possible to individually edit a duplicated Interface Asset generated by API Explorer. Changing any property in the duplicated Interface Asset will always reflect in the original one. In this case, instead, it is best to create a new Interface Asset using API Explorer.
• Re-opening for editing an Interface Asset whose request is behind a firewall or within a local network will no longer contain the previously selected properties or type.
• The cURL type multipart/form-data (aka -F, aks -FORM) is not supported. This kind of request is usually used to upload files like images.
  You can use application/x-www-form-urlencoded instead, but you must add the Content-Type as the header with the application/x-www-form-urlencoded as a value.
• Parameter key and value have to be separated with a colon (‘:’) and a blank space character
• A JSON-formatted response with blank [empty] content before data is not displayed when using Composer or Player for Windows
• API Explorer does not currently support GraphQL architectures
• On iOS devices, the http protocol will not be resolved. Your API Interface Asset should use https instead
• The parameter trailing path must end with a slash, for example: https://url/api/ will work, while https://url/apiwill not work.

Cache management

This is the current cache management mechanisms used by Interface Assets generated with the API Explorer: 

• The request & responses are not cached. There will be no data if you don't have an internet connection when launching the experience in Player. 
• When a resource is downloaded using a web URL, such as an image, the file is automatically cached locally. If, during the same Composer / Player session (i.e. without restarting it), you try to display the same resource, it won't be downloaded again. 
• This media cache is cleared each time you start a new session - i.e. when you restart Composer or Player. 
• If a new request goes into an error state - due to bad parameters or server issues - the last successful answer is kept in memory. You can use the "Request failed" trigger to hide this cached data if it's irrelevant (e.g. stock information).