Create a REST-based Web Service Interface Asset using API Explorer

Table of Contents

    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; displays the contents of any XML or JSON 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 query 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 still possible to manually create an interface asset for a REST-based Web Service, a topic discussed here. However, as you'll discover, not only is it far easier to use API Explorer, but the process is now accessible anyone, of any skill set, and not just developers.

    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 properties you selected are automatically displayed in the scene your 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

    To help you decide which properties would be most appropriate for display within IntuiFace, API Explorer incorporates a machine learning engine. 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 take note of this and how, around the world, IntuiFace users are setting "Price" to the type Currency. Eventually, API Explorer will learn to automatically set "Price" to the Currency type.
    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 check mark).

      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 automatically preselect the "Description" field for visualization.

    NOTE: IntuiLab, IntuiFace and API Explorer respect user privacy and never shares entered information with anyone. The machine learning engine is using user selections to improve the assistance it can provide.

    Modifying your query

    To the left of the Result 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 "araa"

    3. Highlight any part of the Host or Endpoint that 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 representation 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.

    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.

    Modifications made to property types or selected properties will not be reflected in the shared view. 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.

    Result processing

    Sometimes the API responses will not give you the information you need with the right 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.

    YTResult.jpg

    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.

    YTConverter.jpg

    Supported protocols & limitations

    API Explorer can:

    • submit both request URLs and curl statements.
    • process GET and POST requests.
      • a POST parameter can be added to the request body. It will be sent in a JSON object with the following format: {"parameter name": value}
    • consume both XML and JSON-formatted responses. This includes blog feeds as those feeds are formatted using XML.

    Limitations:

    • API Explorer does not yet support OAuth2 authentication.
    • If running more than one instance of Composer on the same PC, only one instance can work with API Explorer. It is not possible for multiple instances of Composer on the same PC to each independently use API Explorer. You must close the instance of Composer that used API Explorer in order to open API Explorer from another Composer instance.