Rest

Parent Previous Next


Rest Source


The "REST Source" allows users to connect to a web service that utilizes a REST API and extract data in XML or Json format. See the Rest Source Connection Manager, Rest Source OAuth Connection Manager,and the Rest Source OAuth2 Connection Manager pages to learn more about configuring the component's connection manager.


Important Notes

Rest Source is available for SQL versions 2012 and higher.

Please see the Configuring Rest Source FAQ for help in configuring popular endpoints.


API Endpoint / Output Columns


  API Endpoint URL - In this field, users set the URL of the web service. Users should also choose whether they are making a call to receive information (Get) or making a request to the service (Post.)

  Get/Post Data - Specifies whether the action is a get or post request. (See your application's API page to determine the appropriate action.)

  Timeout - Sets the amount of time (in seconds) the component should fail if there is no response from the web service.

  Number of Retries - Indicates the number of times to retry connecting to the API before the component fails.

  Results Returned In - Selects the format for the results - XML or Json.

  Cookie Container - Used to identify the variable that stores a returned cookie response. The variable must be of object datatype.


Json, String, and Xml Properties:

 Json Properties

 Xml Properties

 String Properties


Headers



Headers are simply information about the type of data returned.

Users can add and remove headers by clicking the corresponding buttons. Once a header is added, click in its corresponding Name and Variable Name fields to configure them. Headers Values can be replaced by variables using the following syntax: <User::NameOfVariable>.


Pagination Settings


Click here for Pagination Settings help.


Authentication Results





 Secured rest endpoints often need an authentication token for each call made to the REST point. This token may change for each call, therefore, users can create a variable to dynamically set the authentication response token by clicking the Add New Mapping button.  


Test Api



Once properly configured, users can click the Preview Data button to see an output sample as well as return raw XML/Json should users need additional information to help configure the component further.


Endpoints





 Choose Configuration - Users can select available endpoints.  


Http Error Output


The rest source can capture error responses with the Http Error Output. Users are asked to choose between the Rest Source Output and Http Error Output when connecting downstream components. Users should note: an execution error will cause a package to fail unless the Http Error Output is attached.



Error Response Path Property


The rest source depends on failure http status codes. Codes such as 401, 404, and 500 are used to detect if an error has occurred during execution. If an API doesn't return failure http status codes when an error occurs, users can tell the component what to look for. This allows the component to fail with an error.


For example: a user makes a call to an api and it returns a valid status code of 200. If the json response is { "response" : { "error":"Invalid auth token" } }, you can set the Error Response Path to "response.error." The component will detect the error response and throw an exception that can be handled. At this point, the component throws an exception and does not send the error to an error output.

This only applies to endpoints that returns an http status code of 200 instead of using a failure code such as 401 or 404.




Note: the Rest Source will make more than 1 attempt to connect. If the first one fails, the component make all attempts to connect until it either reaches the configured timeout or 5 unsuccessful attempts.