REST Connection

image_pdfimage_print

This connection enables data retrieval from web services that apply the REST (representational state transfer) architectural style. Such “RESTful APIs” are widely used by a variety of service providers.

The REST connection supports REST web services that

  • are based on HTTP
  • use the HTTP methods GET, POST, DELETE, and PUT
  • return data in either JSON or XML format

The REST connection supports the SSL protocol, i.e. HTTPS URLs are allowed. No special parameters are required for its use.

Note: for returned data, only application/xml and application/json are allowed. Content types such as text/plain, text/html, image/gif and image/jpeg are not allowed.

Changes in Jedox version 2019.3:

  • Only connections with HTTP modes GET and POST are possible for JSON and XML extracts. Note: during a data preview of the extract, the POST request is executed, which may provoke undesired changes on the service endpoint.
  • Testing a REST connection with HTTP mode POST no longer executes the HTTP request in 2019.3. Only the reachability of the host is tested in this case.
REST connection with XML load

For XML loads using a connection type REST, the REST connection must use HTTP method POST, PUT, or DELETE. The data may be static or filled dynamically during the load.

Dynamic data: in this case, the request body of the REST connection is filled dynamically during the load with the XML data generated by the XML load. Therefore, the REST connection must have an empty request body in its definition.

Static data: in this case, the XML load must not have a data source assigned. The XML load simply executes the HTTP call as defined in the REST connection.

Main Settings

Resource:

The URL for the source data, e.g. https://abc.example.com/resource.

HTTP Method:

GET

Retrieves a resource but does not modify it in any way (read only). This method is cacheable. GET requires a URL parameter (see below).

POST Creates a new subordinate resource, such as a subdirectory. This method requires a Header Parameter (see below) or Request Body (see Advanced Settings).
PUT Replaces an existing resource or creates a new resource if it does not already exist.
DELETE Deletes a resource.

Header parameters:

The header parameters of the web service as parameter-value pairs. See screenshot below for an example.

URL parameters:

The URL parameters of the web service. Required for GET method. The URL parameter can be anything, as it is specific to the URL used. For example, the screenshot below shows a URL parameter to get a set of data specific to a certain location.

Advanced Settings

Authentication Method:

None No authentication method required.
Basic Basic authentication for REST requests. Requires values for user name and password for the resource
NTLM NT LAN Manager (NTLM), a Microsoft security protocol in a Windows network. Requires values for user name, password, workstation, and domain for the resource.
Token Reference to a separate connection of type OAuthToken, which handles tokens for OAuth2 authentication.

Request Body:

As an alternative to simple body parameters, the complete HTTP body can be specified here. This field is only used for HTTP methods POST and DELETE.

Note: if the connection is used in an XML/JSON load with a source, the request body will be filled dynamically and should therefore be left empty.

SSL Mode:

verify checks the certificate; if response is OK, the certificate is validated.
trust imports the certificate to the keystore, if not yet available
off no SSL is used

Timeout:

The timeout of the web service request in seconds.

Ignore cookies policy:

By default (unchecked), a warning (“Cookie rejected”) appears when the HTTP call breaks a cookie policy. For example, this can be caused by an incorrect domain in the set-cookie header. The REST connection will nevertheless return a result.

If the option is checked, the warning will not appear.

Note: one specific group of supported web services are those that fulfill the OData (Open Data) Protocol. For more information, see http://www.odata.org/.

image_pdfimage_print