REST Data Source


Apps - Datasource - JSON Online icon.png This type of data source belongs to the Online category in the data source library. It is used to define and access a REST resource in order to retrieve dynamic content from websites or third-party products (services) using URIs. URIs are Uniform Resource Identifiers (or endpoints) relying on the REST (Representational State Transfer) HTTP protocol.

Open url.png See  How to choose between a REST data source and a REST (Connector) data source.
SelectDataSourceREST
  • REST data source
    • To define and access a REST resource.
    • Only to access resources without authentication or resources using Basic authentication.
    • To use a given resource from a service occasionally (resource not intended for reuse in another app).

      ==>  The Base URI of the data source is made up of the service and the resource proposed by this service. Note: For Basic authentication, you also need to specify the information required for accessing the service.

      Example documentation icon EN.png
  • REST (Connector) data source
    • To reuse the service and its resources.
    • To access any type of resource for a REST service defined in the app.

      ==>  A REST connector must be created. It must be made up of the service and its resources. Note: For Basic or OAuth 2.0 authentication, you also need to specify the information required for accessing the service.

      Example documentation icon EN.png
      • Create a connector to provide access to the six resources proposed by JSONPlaceholder, a fake REST API with public data used for testing and prototyping:
      • Create a connector to provide access to the resources proposed by Google Calendar:
        • Google Calendar service
        • Resources: By week, by day, by event

 

  • A REST data source relies on a URI made up of a service and a given resource proposed by the service.
ResourcesREST
  • Resources can be as follows:
    • Accessible to all users without requiring authentication, e.g. access to public data.
         ==>  Product name - ev sas.png can interface with all these resources.
    • Restricted to specific users who are first required to authenticate, e.g. access to private data.
         ==>  Product name - ev sas.png can interface with these resources using two authentication methods:
      • Basic: Users must enter their login and password.
      • OAuth 2.0 (Note: Only for the REST (Connector) data source): The login information required depends on the third-party product. Users can access either public data (e.g. general corporate data) or their own data (e.g. user-specific calendar).
  • Once access is authorized, data is read and sent to Product name - ev sas.png in JSON format, a structured text data format.
    • This data can be displayed using widgets. A Selector tool integrated in the data source is used to extract only the data you want.
    • Data is then automatically updated each time that the data source is modified.

Examples

ExamplesREST

1. Third-party products (services) and resources:

  • Examples of services: Gmail, Google Contacts, Google Calendar, Twitter
  • For Twitter, examples of resources: Timeline or followers

         Open url.png  See the other Examples of integration with Product name - ev sas.png

2. Examples based on the authentication method:

  • No authentication required:
    • The http://api.open-notify.org website publishes public data in real-time from the ISS (International Space Station) using REST architecture. The position of the ISS can be displayed using a Google Maps widget without requiring user authentication.
  • Using Basic authentication:
    • Twitter enables users to create their own timelines. Thanks to the REST architecture and the REST API adopted by Twitter, tweets in a user's timeline can be displayed using a Data Viewer widget with prior user authentication.
    • The Salesforce third-party product enables users to have different views of corporate data, e.g. lists of customers, prospects, projects or sales employees. The REST protocol enables you to display these resources using Data Viewer widgets with prior user authentication.
End_ExamplesREST

Notes

Open url.png See General remarks on data sources.

  • The type of authentication that can be used depends on the API set up by each third-party product and is described in the documentation of the API. 
  • To find out more about the JSON table structure, please consult http://www.json.org.
  • To access resources using OAuth 2.0 authentication, use the REST (Connector) data source.

Caution

  • Basic authentication encrypts and stores the login information required by the third-party product in Product name - ev sas.png.

Best Practice big icon.pngBest practice

  • If a third-party product uses a REST API and offers access via different authentication methods, we recommend that you use OAuth 2.0 authentication whenever possible if supported by Product name - ev sas.png. In this case, you should use the REST (Connector) data source.

List of properties

Content

Authentication Type: User authentication method for accessing the data source, e.g. website or third-party product, via the REST data source.

  • None: No authentication is required for accessing the service because the REST API is open or public.
  • Basic: Authentication is performed using Product name - ev sas.png and communicated to the third-party product via parameters in the URL.

Base URI: URI for accessing the REST data source which is made up of a service and a given resource proposed by the service.

Basic Authentication Parameters: Only for Basic authentication. Login and password are required in order to access the resource. 

  • Click Apps - Edit icon.png to enter the information.
  • To check that you have entered the login information correctly, you can tick the Show my password box.
             EVApps - datasource REST - Basic Parameters.png
Selector

Selector: Access to the tool for extracting the data you want from the JSON table which contains all data retrieved from the resource.

  • The JSON table contains a list of tags surrounding data subsets using curly brackets, { }.
  • You can select the Selector tool using an expression in the search field (1) or by selecting a tag from the JSON table (2).
             EVApps - datasource REST - Selector.png

    Open url.png  To find out more about:

  • The JSON data structure: json.org
  • The use of regular expressions in the search field (1): JSONSelect
End_Selector
SelectFirstRowAsCurrentRecord

Select First Row As Current Record: Used to indicate if the first record of the data source, when displayed in widgets, is selected by default (box is checked) or if no record is selected by default (box is not checked). 

NoDataMessage

No Data Message: Message displayed when no data is returned in the data source. Enter the code directly in the field or click Apps - Edit Html icon.png to open the text editor

AutoRefresh

Auto Refresh (Note: Only for dynamic data sources): Used to indicate the automatic refreshment interval for a dynamic data source. The frequency is expressed in hours/minutes. The updating of data is done in execute mode or edit mode, each time the app is run and each time the page is redisplayed.

    Best Practice icon.png

  • Because the updating of data requires additional activity on the EasyVista Service Apps platform, you should define an automatic refreshment interval only if the app is required to constantly display  real-time data for long periods of time on a screen.
             Example documentation icon EN.png  Dashboards
  • You should not define an automatic refreshment interval if the app is only used for displaying a snapshot of data for short periods of time.
             Example documentation icon EN.png  A portal for consulting catalogs

Master/Detail

SectionMasterDetail

Master Data Source: In a master-detail relationship, this is the name of the master data source linked to the current data source.

Master Field: Name of the primary key in the master data source used to establish the link with the current data source. As a general rule, it is the PK (Primary Key) column in the Product name - ev itsm.png table.

Detail Field: Name of the EasyVista data source column identifying the key in the Product name - ev itsm.png table. As a general rule, it is the column whose prefix is FK (Foreign Key).

Example documentation icon EN.png You want to display all actions (detail data source) associated with an incident (master data source):

  • Master Data Source = Incidents data source defined using the Operation > Incidents > All Incidents parent query.
  • Master Field = PK identifying the Incident_ID column in the Incidents table.
  • Detail Field = FK_AM_ACTION_REQUEST_ID identifying the action number related to the incident.

Procedure: How to define a REST data source

1. Click Apps - Add datasource icon.png in the Objects pane. Open the Online category and select the REST data source Apps - Datasource - JSON Online icon.png.

2. Specify the data source in the Base URI field.

3. Select the authentication method required by the resource: None or Basic.

  • For Basic authentication, click Apps - Edit icon.png next to the Basic Authentication Parameters field. Enter the login and password.

4. You can narrow down the data to be displayed using the Selector tool.

  • Click Apps - Edit icon.png next to the Selector field.
  • You can click the tag you want in the JSON table (Note: It will appear in yellow). You can also enter an expression in the search field and click [ APPLY ].
  • Click [ OK ].

5. Add the type of widget for displaying the selected data and point it to the REST data source that you just configured.

SAS_IntegrationRESTAboutTheUse

About the use of the third-parties REST API

Please note that numerous software companies limit the access to the REST API of their software, generally by basing itself on a number of calls by hour/day/month.
Moreover, only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
Finally, some software companies set up plans (for example Classic, Professional, Enterprise, etc.) for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.

The possible cost of the use of the third-parties API by means of Product name - ev sas.png is not taken care by Logo - EasyVista.png.

References and useful links

Examples of integration

Agile CRM  Logo - Agile CRM.png 

Oracle Marketing Cloud (Eloqua)  Logo - Oracle Eloqua.png

XWiki  Logo - XWiki.png

WordPress  Logo - Wordpress.png

Freshdesk  Logo - FreshDesk.png

Zendesk  Logo - ZenDesk.png

UserVoice  Logo - UserVoice.png

Tags:
Last modified by Christine Daussac on 2017/09/01 16:49
Created by Administrator XWiki on 2014/11/12 20:39

Shortcuts

Recent Updates

Haven't been here in a while? Here's what changed recently:

-   Product name - ev itsm.png
-   Product name - ev sas.png

Interesting Content

How to Automate Integration
Add a Shortcut to an App
History
Quick Dashboard
Full text search - Stop Words

Powered by XWiki ©, EasyVista 2018