DSS REST API

This section describes the Data Source Solutions DSS REST API functionality.

The REST APIs are provided for advanced users who want to script DSS interactions and for developers who want to integrate DSS into their applications.

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

Interfaces

DSS 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 DSS:

• 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 DSS prototype. For more information about DSS prototype, see Prototype Specification.

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

Versioning

The REST API for DSS is version independent but is closely related to the DSS version. A single DSS 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 DSS 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 DSS version that released the specific version of the API. Therefore, the API version looks similar to the DSS version.

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

Version in the REST Request URL

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

• For authentication request (Login), irrespective of the DSS version, /v1 must be used.
• For DSS 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 DSS Hub Server.
• For DSS versions prior to 6.0.5/0, /latest or /v6.0.5 must be replaced with /v0.

Supported API Versions

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

curl -H "Authorization: bearer <em>access_token</em>" <em>hub_server_url</em>/api

Example Request:

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

Example Repsonse:

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

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

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"}}
   

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

3. Run the cURL command.
   For example:

   {% tabs %}

   {% tab label="Linux" %}

   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
   

   {% /tab %}

   {% tab label="Windows" %}

   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
   

   {% /tab %}

   {% /tabs %}

Status Codes

Related Articles

• REST API Examples
• Prototype Specification
• REST API Reference