1. Transportation and Global Trade Management Data Export Rest API DocumentationREST API for Fusion Cloud Transportation and Global Trade Management Data Export
  2. Quick Start

Quick Start

The primary use case for this REST API is to trigger an asynchronous process to select content from one or more database tables and send as CSV formatted data to an external repository. Let's first send a simple REST HTTP request to export the content of three columns of the SHIPMENT table.

Note:

The capability also exists to process a request for a single table synchronously although this method will produce limited data i.e. the volume of data will be limited and there is no capability to "page" through a result list.

Step 1: Consider Before You Start

Review the basics. If you're new to REST APIs, make sure you understand the basics of REST and JSON, and scan our list of important terms.

Note:

A convention is used in this document for template parameters in example request URLs or message bodies when real data is to be substituted to make the example accurate. The information to be substituted will be delineated by angle brackets, i.e. "<" and ">". For example: <username>. If the actual value to be used is GUEST.ADMIN, the full template string including angle brackets should be substituted i.e. <username> should be replaced with GUEST.ADMIN.

Choose a client. REST APIs connect software programs over the HTTP protocol. You need a software client to send the HTTP requests. In our examples, we use cURL. But cURL isn't the only tool you can use.

Step 2: Get Your Oracle Transportation and Global Trade Management Cloud Account Info

To make a REST HTTP request, you need to gather a few bits of information, including:

  • REST Server URL: Typically, the URL of your Oracle Cloud service. For example, https://servername.us2.oraclecloud.com.

  • Authentication Credentials: An Oracle Cloud service user with permissions to access the resources you're using. These credentials will depend on the authorization method selected for the requests. The REST API supports SSO, HTTP Authentication (Basic) and the OAuth 2 Client Credentials flow.

You can find the REST Server URL, user name, and password in the welcome email sent to your Oracle Cloud service administrator.

Step 3: Configure Your Client

With the information gathered so far, you're ready to configure your client to send a REST HTTP request.

  1. Construct the request URL. The URL consists of the server name and the resource path: 

    https://<server>/<resource-path>

    The <server> is the REST Server URL from Step 2, as in: 

    https://servername.us2.oraclecloud.com

    The <resource-path> is the relative path or endpoint to the REST resource you're working with. You can pick any endpoint in All REST Endpoints. Refer to Resource Paths for how to construct the URL for your target resource. For example, to get export request statuses: 

    /logisticsRestApi/data/v1/exportStatuses

    Combine the REST Server URL and, in this example, the order release REST resource path and your request URL is complete.

    https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportStatuses

  2. Provide your account information. Include your user name and password (from Step 4 below) in the client. you can specify your account information using the -u parameter as follows: 

    -u <username:password>

  3. Set the media type. Media type defines the structure of the HTTP payloads exchanged between the server and the client. For example, if you're using cURL to POST data, you can specify a message body media type using the -H parameter as follows: 

    -H "Content-Type: <chosen media type>"

    Note:

    The "Content-Type" header parameter is required for POST & PATCH requests as they are the only supported operations which send a message body. The GET operation will specify the HTTP "Accept" header to specify the required response media type.

When you're done, the complete cURL to perform a GET command should look like this:

curl -u <username:password> -X GET \ https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportStatuses

The complete curl command to perform a POST should look like this:

curl -u <username:password> -X POST -H "Content-Type: application/json" \ POST https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportRequests -d '..request message content..'

The -d parameter specifies the data to be sent as the message body.

If you're an advanced REST user, but are reading our Quick Start anyway, you might want to configure Cross-Origin Resource Sharing (CORS) now. Otherwise, you're ready to move on to Step 4.

Step 4: Authenticate and Authorize

Authentication proves that your credentials are genuine, and authorization allows you to apply your access privileges.

Authentication

Single Sign-On (SSO)

The /logisticsRestApi/data URI is protected by the SSO server. In this case access to the REST API should originate from the browser. This can be accomplished by creating a rich JavaScript application. Calls to the rest API can be made in the user's context when protected by an SSO server. This requires Cross Origin Resource Sharing (CORS) to be set up on the OTM server.

HTTP Authentication (Basic)

The /logisticsRestApi/data-int URI is not protected by the SSO server. This URI requires the HTTP basic authentication authorization header. It also requires a staged integration user in OTM. The header is required to be the Base64 encoded user name and password of the staged integration user.

Note:

The -u parameter for the curl command expects the plain text values and performs the Base64 encoding before sending in the HTTP header.

OAuth 2 Client Credentials

Use of OAuth 2 requires configuration of the Oracle Identity Cloud Service (IDCS) to provide the authorization service for this OAuth 2 flow. See the Oracle Fusion Cloud Transportation and Global Trade Management Integration Guide for configuration information.

To make sure data access over a network is secure, Oracle Transportation and Global Trade Management REST APIs requires Transport Layer Security (TLS).

Let's look at our example using Basic authentication over TLS. To authenticate, you must submit the user name and password for your Oracle Cloud account. Typically, the user name and password are encoded in Base64 format, as in: 

curl \
-X GET https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportStatuses \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

As mentioned, you can use the -u curl option to pass the plain text user name and password for your Oracle Cloud account, as in this example: 

curl -u username:password \
-X GET https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportStatuses

Authorization

Authorization enforces access privileges by service role. Access to the Data Export API requires the "Data Replication Service - REST" role to be granted by an administrator.

See Access Control Lists for details.

For additional details, including how to assign privileges to user and user roles, see the "Manage User" topic in the online help.

Step 5: Send an HTTP Request

You're almost done. Now that your authentication and authorization are set, you're ready to send a test HTTP request. The simplest command to test is to get the status of any export requests that have previously been created. Obviously, for a first attempt in a new server, the returned array list will be empty (and the "count" below will be zero) but receiving this response will confirm authentication, authorization, and HTTP syntax. You can do this using the get request in cURL: 

curl -u username:password -X GET -H "Accept: application/json" \ https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportStatuses

If your request fails, and you're using curl, review the response comments, adjust your request, and then try again. If you're using other REST clients, review the failure Status Codes, and then try again. 

{    
    "count": 25,
    "items": [
        {
            "progress": "succeeded",
            "startTime": {
               "value": "2022-01-01T09:00:00Z"
            }
            ..etc..
         },
        {
            "progress": "failed",
            "startTime": {
               "value": "2022-01-02T09:00:00Z"
            }
            ..etc..
         },
         ..etc.. (more items)
    ] 
}

Continuing with the example of exporting content from the SHIPMENT table, the full structure for the request message will be described in Tasks section for Export Requests. For this quick start we will just use a simple request to test authentication, authorization, and HTTP syntax.

curl -u <username:password> -X POST -H "Content-Type: application/json" https://servername.us2.oraclecloud.com/logisticsRestApi/data/v1/exportRequests -d '{
    "schema": "PRIMARY",
    "rangeAfter" : {
        "value": "2022-09-01T00:00:00Z"
    }
    "tables" : {
        "items" : [
            {
                "tableName": "SHIPMENT",
                "selectList": "SHIPMENT_GID,SHIPMENT_NAME,PERSPECTIVE,INSERT_DATE,UPDATE_DATE"
            }
        ]
    }

}'

Note:

A "schema" value of "PRIMARY" is required to correctly identify the SHIPMENT table.

If your database contains shipments that were inserted or updated after 1st Sep 2022 at Midnight UTC, then the response should look like the following: 

SHIPMENT
SHIPMENT_GID, SHIPMENT_NAME,PERSPECTIVE,INSERT_DATE,UPDATE_DATE <domain>.<XID1>,<name1>,B,<date>,<date>
<domain>.<XID2>,<name2>,B,<date>,<date>
<domain>.<XID3>,<name3>,B,<date>,<date>

For more information: