REST API Examples

This section lists few examples of how to use the Fivetran HVR REST API.

Before proceeding with this section, it is recommended to read Prototype Specification, and details for each REST API request is available in REST API Reference.

You can use cURL to execute HVR REST API methods (GET, POST, PUT, PATCH, DELETE) from the command line. cURL is a command-line tool for getting or sending data including files using URL syntax.

Data (-d or --data) can be supplied directly on the command line or via a data file. For more information, see section Supplying Data.

This is an example for logging into HVR using REST API. The user name myhubuser and password myhubuserpass supplied here is for the hub user.

The access_token generated in the response for login must be used in all other REST API request headers for authentication.

Request:

curl \
-X POST \
-d '{"username": "myhubuser", "password": "myhubuserpass"}' \
-H "Content-Type: application/json" \
http://localhost:4340/auth/v1/password

Response:

{
      "token_type": "bearer",
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6pXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJW5l2w1bRxU",
      "expires_in": 900
}

Generating and Using One-Time Login Tokens

Since v6.1.5/8, a user can log in using a pre-generated one-time login token. The login token can be exchanged (once) for the access token (and optionally the refresh token). This requires Authentication_Method hub server property to contain "login_token":true.

This is an example for generating a login token.

Request:

curl \
-X POST \
-d '{"username": "myhubuser", "password": "myhubuserpass"}' \
-H "Content-Type: application/json" \
http://localhost:4340/auth/v3/login_token

Response:

{
      "login_token": "6QzUpevCxYXDwy7LJyA1sDHFfubhhaFK11Bf38wIk0E",
      "login_url": "http://localhost:4340#/login?token=6QzUpevCxYXDwy7LJyA1sDHFfubhhaFK11Bf38wIk0E",
      "expires_in": 900
}

This is an example for logging in using the login token:

The access_token generated in the response for login must be used in all other REST API request headers for authentication.

Request:

curl \
-X POST \
-d '{"login_token": "6QzUpevCxYXDwy7LJyA1sDHFfubhhaFK11Bf38wIk0E"}’ \
-H "Content-Type: application/json" \
http://localhost:4340/auth/v3/token

Response:

{
      "token_type": "bearer",
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6pXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJW5l2w1bRxU",
      "expires_in": 900
}

Create Location

Following is the format for creating a new location in HVR using the REST request. For more information about this REST request, see Add location (/hubs/{hub}/definition/locs) in Definition Interface.

For creating a location, it is mandatory to define the location name (loc) and location properties (props). The action definition (actions) is optional.

'loc' : <ident>            - parameter for defining name for the location
'props' : {                - parameter for defining location properties that are required for location creation
    prop<str> *: value<typeof_loc_prop>
}
'actions' ?: (             - parameter for defining action with parameters for the location
    { 
        'type' : <ident>
        'params' ?: { 
            param<str> *: val<scal>
        }
    }*
)

After creating a location, it is recommended to test the location connection using Test Location Connection (/hubs/{hub}/locs/{loc}/test) in File and DB Browse Interface.

Examples

Following are a few examples for creating a new location in HVR using a REST request.

For authentication, the access_token received in the login response must be supplied in the location creation request.
A space is required before and after the word Bearer (-H "Authorization: Bearer access_token).

Oracle

Example for creating a new Oracle location named mylocation.

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

If the location property Capture_Method is not defined, then this location can be used only as a target/integrate location.

SQL Server

Example for creating a new SQL Server location named mylocation.

curl \
-X POST \
-d '{"loc":"mylocation", "props": {"Class": "sqlserver", "SqlServer_Server": "myserver", "Database_Name": "mydb", "Database_User": "mydbuser", "Database_Password": "mydbuserpassword", "Capture_Method": "DIRECT", "Supplemental_Logging": "CDCTAB_ARTICLE", "Log_Truncater": "CAP_JOB"}}' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDIxNjM0NTJ9.f6FYvAb7xh9DWtaJd_Y7-3vIeq9UIotFEoLutP5Qhgw" \
-H "Content-Type: application/json" \
http://localhost:4340/api/latest/hubs/myhub/definition/locs

If the location property Capture_Method is not defined, then this location can be used only as a target/integrate location.

Snowflake

Example for creating a new Snowflake location named mylocation.

With staging:

curl \
-X POST \
-d '{"loc":"mylocation", "props": {"Class": "snowflake", "Database_Host": "myserver", "Database_Port": 443, "Snowflake_Role": "admin", "Snowflake_Warehouse": "mysnowflakewarehouse", "Database_Name": "mydb", "Database_Schema": "mysnowflakeschema", "Database_User": "mydbuser", "Database_Password": "mydbuserpassword", "Staging_Directory": "/mystagingdir", "File_Scheme": "s3s", "S3_Bucket": "mybucket", "AWS_Access_Key_Id": "TWENDUIOWNDH1Q", "AWS_Secret_Access_Key": "N5D98Ae0EssvnPaBXlCJiBmpyMpmiD"}}' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDIxNjU3MDN9.__QAHe15Mjz0YJGG3ZevgQkR0SO7cNIN0XRiZ9b6cfg" \
-H "Content-Type: application/json" \
http://localhost:4340/api/latest/hubs/myhub/definition/locs

Without staging:

curl \
-X POST \
-d '{"loc":"mylocation", "props": {"Class": "snowflake", "Database_Host": "myserver", "Database_Port": 443, "Snowflake_Role": "admin", "Snowflake_Warehouse": "mysnowflakewarehouse", "Database_Name": "mydb", "Database_Schema": "mysnowflakeschema", "Database_User": "mydbuser", "Database_Password": "mydbuserpassword"}}' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDIxNjU3MDN9.__QAHe15Mjz0YJGG3ZevgQkR0SO7cNIN0XRiZ9b6cfg" \
-H "Content-Type: application/json" \
http://localhost:4340/api/latest/hubs/myhub/definition/locs

Sybase ASE

Example for creating a new Sybase ASE location named mylocation.

curl \
-X POST \
-d '{"loc":"mylocation", "props": {"Class": "sybase", "Sybase": "/sybaseinstall_loc", "Sybase_CT_Library": "/sybase_ct_lib", "Database_Host": "mysybasenode", "Database_Port": 5000, "Database_Name": "mydb", "Sybase_Authentication_Method": "USER_PASS", "Database_User": "mydbuser", "Database_Password": "mydbuserpassword", "Capture_Method": "DIRECT", "Archive_Log_Path": "/logs",}}' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFsdGE6NTY5MDAiLCJzdWIiOiJodnIiLCJleHAiOjE2NDIxNjY4NTJ9.8Ys5Zzk8AOdeAQ6GfeyXxIZ1iTfcxucnzuaJoA27A5o" \
-H "Content-Type: application/json" \
http://localhost:4340/api/latest/hubs/myhub/definition/locs

Refresh Data

This is an example for refreshing data in HVR using API. For more information about this REST request, see Post Refresh event and schedule a job for it (/hubs/{hub}/channels/{channel}/refresh) in Activate, Refresh, and Compare Interface.

It is mandatory to define source (source_loc) and target location (target_loc) name for refreshing data, all other parameters are optional.

curl \
  -X POST \
  -d '{"start_immediate":true,"source_loc":"mysrclocation","target_loc":"mytgtlocation","granularity":"bulk"}' \
  -H "Authorization: Bearer cCI6IkpXVCJ9.eyJpc3MiOiJodHRHAiOjE2NDI0OTkwOi8vZ2Fib246NTY5MDAiLCJzdWIiOiJodnIiLCJle0NDF9.Rn4eJhDfI2fmDwKh_iiozgPrayfeDAVR6wlyeyJhbGciOiJIUzI1NiIsInR5849DMAp" \
  -H "Content-Type: application/json" \
  http://localhost:4340/api/latest/hubs/myhub/channels/mychannel/refresh