REST API

This section describes the Fivetran Local Data Processing REST API functionality.

The REST APIs are provided for advanced users who want to script Local Data Processing interactions, and for developers who want to integrate Local Data Processing into their application.

Representational State Transfer (REST) API is a simple, stateless architecture style (not a protocol) that uses the HTTP/HTTPS method (such as GET, PUT, POST, DELETE) to retrieve the management information from the database. The main advantage is that it has a simple interface and can be modified even when Local Data Processing is running.

Interfaces

Local Data Processing has close to 200 REST API end-points and these are grouped into 'interfaces'. Most REST end-points return a JSON response and many also accept a JSON request.

Following are the REST interfaces in Local Data Processing:

• Activate, Refresh, and Compare Interface
• Agent Configuration Interface
• Alert Interface
• Authentication Interface
• Control Message Interface
• Definition Interface
• Encryption Interface
• Event Interface
• File and DB Browse Interface
• Hub Config Interface
• HubServer Interface
• Job Interface
• License Interface
• Logfile Tailing Interface
• Miscellaneous Interface
• Query Interface
• Repository Config Interface
• Statistics Interface
• Table Adapt Interface
• User Config Interface

The specification for each REST end-point defines the structure of this JSON using a syntax called Local Data Processing prototype. For more information about Local Data Processing prototype, see .

An example for how to use REST API is available in section .

Versioning

The REST API for Local Data Processing is version independent but is closely related to the Local Data Processing version. A single Local Processing Hub Server can serve multiple version of the REST API, so that older Command Line Interface (CLI) clients and user written API clients continue to work, even if the Local Processing Hub Server was upgraded with a new version of the REST API.

A new API version is released only when there is a change in the API. The REST API version is defined as the Local Data Processing version that released the specific version of the API. Therefore, the API version looks similar to the Local Data Processing version.

Note that the string representation in API version contains only '.' instead of the '/'. For example, when Local Data Processing version 6.1.0/1 got released with changes in API, it then serves /api/v6.1.0.1. Later, when Local Data Processing version 6.1.0/2 is released but does not have any API changes, then it still serves /api/v6.1.0.1.

Local Data Processing and are not dependent on API version, which means you can inspect or changes values of newer Local Data Processing properties or actions using an older version of API. For example, a new property or action parameter introduced in Local Data Processing version 6.1.0 can still be inspected and changed using an older API version like /api/v6.0.5.

Version in the REST Request URL

This section describes about the version number to be used in the REST request URL.

• For authentication request (), irrespective of the Local Data Processing version, /v1 must be used.
• For Local Data Processing versions 6.0.5/0 and above, /latest may be used instead of the actual version (e.g. /v6.0.5). /latest will be automatically converted to the highest known version by the Local Processing Hub Server.
• For Local Data Processing versions prior to 6.0.5/0, /latest or /v6.0.5 must be replaced with /v0.

Supported API Versions

To list the Local Data Processing API versions supported by your hub server, use the following cURL statement:

curl -H "Authorization: bearer access_token url
content_copy

Example Request:

curl -H "Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6pXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJW5l2w1bRxU" http://localhost:4340/api
content_copy

Example Repsonse:

["v0","v6.0.5","v6.0.5.1"]
content_copy

Supplying Data

Normally, the data (-d or --data) is supplied directly on the command line. To send large amount of data or to avoid escaping of special characters in the Windows command prompt, you can use a data file to supply data from the command line.

Supplying Data Directly on Command Line

Example for supplying data directly on the command line:

curl \
-X POST \
-d '{"loc":"mylocation", "props": {"Class":"oracle", "Oracle_Home":"/oracle/1900", "Oracle_SID":"ORA1900", "Database_User":"mydb", "Database_Password":"mydbpassword", "Capture_Method":"DIRECT"}}' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDIxNjI3MTh9.Fd5x4uGzRimvj8Ykq867lXQTWuIQBVELzhvn3mfPv8U" \
-H "Content-Type: application/json" \
http://localhost:4340/api/latest/hubs/myhub/definition/locs
content_copy

Supplying Data from File

Following is the procedure to supply data from a file:

1. Create a JSON file with the required data.
   For example, to create an Oracle location:

   {"loc":"myloc_file", "props": {"Capture_Method":"DIRECT","Oracle_Home":"/oracle/1220","Oracle_SID":"ORA1220","Database_User":"mytestdb","Database_Password":"testdbpass", "Class":"oracle"}}
   content_copy

2. Save the JSON file (e.g. mydata.json).

3. Run the cURL command.
   For example:

   LinuxWindows

   curl \
   -X POST \
   -d @mydata.json \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDI0MTcwNTF9.mmYpa_It9Mj5p0I_HBceHTdu_4-HJj_yqWyYMVgLyhg" \
   -H "Content-Type: application/json" \
   http://localhost:4340/api/latest/hubs/myhub/definition/locs
   content_copy

Status Codes

Code	Name	Description
200	OK	Indicates that the request has succeeded.
201	Created	Indicates that the request has succeeded and a new resource has been created as a result.
400	Bad Request	Indicates that the request could not be understood by the server, probably due to incorrect syntax.
403	Forbidden	Indicates that the user does not have execution access rights.

Related Articles