Skip to main content

REST API

  • Updated

The REST API data source in Analytics enables you to extract data from a web application.

Connecting to a REST API

To configure a REST API data source, you will need to enter the following information:

Configuring-REST-API-Data-Source_All.png

  • Default name of the data source: By default, Analytics names it REST API. You can change it to your preference.

  • URL: the URL where the service is located.

  • Method: from the dropdown menu, you can choose your preferred request type - GET, POST or PUT.

Unsupported method. If the REST service does not support your method (e.g., POST), you will receive an error message.

  • Result Type: You can specify the file type you expect to be retrieved from the REST API. For example, if you choose .csv and the REST API responds with a JSON, Analytics will try to parse the file as a .csv.

  • If you choose Auto Detect, SM Analytics will use the information about the file (content) type, coming from the REST API to parse the file.

  • Credentials: after selecting Credentials, you will be able to enter the credentials for your REST API or select existing ones if applicable. You can also pick the No Account option.

Working with URL Parameters

Parameters are a way to specify and sort content on a web page. You can provide path and query parameters in your URL when configuring the REST API data source in order to change the received data

To use parameters effectively follow the procedure below:

  • Provide parameters in the URL. You must put path parameters in curly braces and specify query parameters after a question mark (?). You can see in the example below both path, and query parameters are color-coded in blue to make them more easily identifiable.

    Configuring-REST-API-Data-Source_All.png

  • Add parameters' values. In the following screen, specify the value of each parameter you have added in the URL.

    Parameters-Values-Rest-API.png

    As a result, the REST API service will respond with the data on the provided URL in a REST compliant format. Generally, you will receive a JSON file:

    REST-API-Data-Format-Result.png

    After loading the data, you will continue to the Visualization Editor screen.

Unsupported File Formats. If the REST API responds with a file format, which is not supported by Analytics (e.g., XML), you will not be able to create visualizations with the data in this file.

  • Change the parameters' values without losing your visualization data. Changing the parameters' values after you have started building your visualization offers a variety of possibilities. For example, you can change the city code path parameter for your weather rest API and have a new dataset loaded for this new city. The information for the visualization you have already built will be automatically updated with the new data.

    To do this, click on the file icon in the upper-left corner of the Visualizations Editor screen.

    REST-API-Change-Parameters-Values.png

    In the screen that opens, click the REST API Parameters button.

    REST-API-Parameters-Button.png

    You will be redirected to the screen in step 2 where you can provide new values to your parameters.

Losing Your Data Warning Sometimes when you change the values of your parameters, there might be a chance to lose the visualization you already created in the Editor. In this case, а warning message will appear when you click/tap the Load Data button. If you choose to continue, you will have the new dataset loaded in the editor and you will have to start building your visualization from scratch.

Choosing a Method

The Method in your REST API data source configuration represents a request used to interact with resources in a REST system. The request generally consists of:

  1. A path to a resource (URL)

  2. HTTP verb:

    • GET - to retrieve a specific resource

    • POST - to create a new resource

    • PUT - update a specific resource

  3. A Header: allows the client to pass along information about the request

  4. A Body: an optional message (when using POST and PUT methods) containing data

Working-With-Methods.png

For more information about the Header and Body of a request, please refer to this link.