REST API for Fusion Cloud Transportation and Global Trade Management Business Object Resources

Quick Start

You can make many types of HTTP requests using Oracle REST APIs. You can easily make requests to view, create, update, or delete business object resources. You can even request asynchronous processing rather than the default synchronous processing. But let's first send a simple REST HTTP request to find out the structure of an order release object.

Note:

The capability also exists to send out REST resource content to external systems, e.g. triggered by an automation agent.

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.

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. To help you choose one, see Work with your REST API Client.

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. As of version 21A, 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.

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, we're interested in the order release resource:
```
/logisticsRestApi/resources/v2/orderReleases
```
Combine the REST Server URL and, in this example, the order release REST resource path and your request URL is complete. For more information, see URL Paths.
```
https://servername.us2.oraclecloud.com/logisticsRestApi/resources/v2/orderReleases
```
Provide your account information. Include your user name and password (from Step 4 below) in the client. For example, if you are using cURL, you can specify your account information using the -u cURL command as follows:
```
-u <username:password>
```
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, you can specify a resource item media type using the header -H command.

Note:

The "Content-Type" header parameter is not required for GET requests as there is no request body. It will be required for POST & PATCH requests.

For more on media types, see Supported Media Types.

When you're done, the complete cURL command should look like this:

curl -u <username:password> \
 -X GET https://servername.us2.oraclecloud.com/logisticsRestApi/resources/v2/orderReleases HTTP/1.1

If you're not familiar with any of the syntax used in the example, check out Work with your REST API Client.

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/resources 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/resources-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 you create is the Base64 encoded user name and password of the staged integration user. Unless otherwise stated, all following examples will use the "resources" path element for consistency but these should obviously be replaced with "resources-int" if using basic authentication.

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 Oracle Transportation and Global Trade Management Cloud 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/resources/v2/orderReleases HTTP/1.1 \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Alternatively, you can use the -u cURL option to pass the 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/resources/v2/orderReleases

Authorization

Authorization enforces access privileges by service role and there are two roles (Access Control List) for each root resource; update (for POST, PATCH and DELETE) and view (for GET)". To provide access to a resource the corresponding Access Control List must be granted to the particular User or User Role. If, for example, you want a User Role to be able to only View Items you would grant permission to "REST - Item - View". Similarly, if you also wanted the User Role to be able to create and modify Items you would also grant them access to "REST - Item - Update".

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. Continuing with our example, we want to get all the information about the structure of the Order Release object in REST. You can do this using the get request in cURL:

curl -u username:password \
 -X GET https://servername.us2.oraclecloud.com/logisticsRestApi/resources/v2/orderReleases

If your request for information about the Order Release object is successful, you receive a response with a body similar to the following abbreviated example. 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.



{
    "hasMore": true,
    "limit": 25,
    "count": 25,
    "offset": 0,
    "items": [
        {
            "orderReleaseXid": "ORDER RELEASE 01",
            "orderReleaseName": "SAMPLE ORDER 01",
            "isTemplate": false,
            ..etc..
         },
        {
            "orderReleaseXid": "ORDER RELEASE 02",
            "orderReleaseName": "SAMPLE ORDER 02",
            "isTemplate": false,
            ..etc.. (more attributes)
         },
         ..etc.. (more items)
    ],
    "links": [
        {
            "rel": "next",
            "href": "https://servername.us2.oracle.com/logisticsRestApi/resources/v2/orderReleases?offset=25"
        },
        {
            "rel": "self",
            "href": "https://servername.us2.oracle.com/logisticsRestApi/resources/v2/orderReleases"
        }
    ]

Learn about common processes in the Use Cases section.
Learn about collections of resources in the Manage Collections section.
Learn about outbound resources in the Outbound REST section.
Join the Oracle Developer Community, where you can share tips and advice with others.