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 querFy 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.

    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 need to 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 of through its associated action.

    APX-100.jpg

    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.

    Properties, Triggers & Actions

    Properties

    All Interface assets generated by the API Explorer will have the following properties.

    • Automatic refresh: check this property to make sure your content is refreshed on a regular basis.
    • Refresh time: the periodicity of the automatic refresh, if activated. Warning: be careful to respect your web service quota and

    REST_props.png

    All the other properties will depend on your web service parameters.

    Any parameter set in the query, header or body of the request will appear in the properties panel.

    The response of the web service will appear as read-only properties and can be accessed through a binding.

    Triggers

    All Interface assets generated by the API Explorer will have the following triggers.

    • Request started: raised when the request is sent.
    • Request completed: raised when a response is received with a success code (200).
    • Request failed: raised when no response or an error is received. This trigger contains the following read-only parameters:
      • Status code: the HTTP code returned by the server.
      • Raw response: the response or error message received.

    REST_triggers.png

    Actions

    All Interface assets generated by the API Explorer will have the following actions.

    • Refresh: use this action to manually refresh the content retrieved through this web service.
    • Set Automatic refresh: dynamically change the Automatic refresh property.
    • Set Refresh time: dynamically change the Refresh time property.

    REST_actions.png

    All the other actions will depend on your web service parameters.

    Any parameter set in the query, header or body of the request will appear as a Set {Parameter name} action so you can dynamically change it.

    In case of a POST, PUT, PATCH or DELETE method, it will appear as an action.

    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, 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.
    • gzip and deflate compression methods are supported.

    Limitations:

    • API Explorer only supports Basic or Bearer authentication. It does not yet support Digest or OAuth2 authentication.
    • 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.