OTM and REST APIs

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |

Training Session: Logistics REST APIs

Chad Walkowiak Yu Liu August 15, 2016

Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |

Safe Harbor Statement

The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.


Session Overview

• This will be a technical session discussing the REST API that is now part of the Logistics product.

• Topics will include REST, HTTP, JSON, Entities, cURL, Authentication, ACLs, etc.


Agenda

• Overview of REST and JSON

• Logistics Integration Methods

• Introduce the Logistics REST API

• Authentication and Authorization

• Examples

• Documentation

• Best Practices


Overview of REST and JSON – Overview of REST

• REST is an architectural style to implement web services that are lightweight and scalable

• Identifying resources based on a URI

• Act upon those resources using HTTP Methods

– GET retrieves a resource

– POST updates a resource

– PUT creates a resource

– DELETE deletes a resource


Overview of REST and JSON – Overview of JSON

• JSON is a readable file format

• Less verbose than XML

• Provides the ability to represent hierarchies of data

• Supported in many programming languages


Overview of REST and JSON – JSON vs XML

http://www.pcmag.com/encyclopedia/term/56790/json


Logistics Integration Methods

• Bulk operation methods

– WMServlet

– SOAP API

– Integration Cloud Service

• Use case for REST API

– Synchronous

– Building custom UIs


Logistics Integration Methods Use Cases

Use Case Integration Method Uploading nightly Orders Bulk Integration Method

Uploading Rates Bulk Integration Method

Create single page Order screen REST API

Create a Shipment UI specific for rail REST API


Introduce the Logistics REST API

• URI format

– http://host/GC3/api/sdo/entityName - Perform REST Operations

– http://host/GC3/api/metadata/entityName - Retrieve XML Schema

• Works at the Entity level – Entities include OrderRelease, Location, BuyShipment

– Entities represent an entire object hierarchy • Shipment

– Shipment Refnum

– Shipment Stop

• Shipment Ship Unit

• The JSON Payload is based on this hierarchy


Introduce the Logistics REST API

• Changes to this structure may change in a release

– Unlike the integration schema it will be the customer’s responsibility to change their apps accordingly.

• Updates handle Object Locks and Cache Refreshes

– Behaves the same as updates via the UI


Authentication and Authorization

• Secured with HTTP Basic Authentication

• Highly recommend running over HTTPS

• Creating Access Control Lists to group Entities

– Similar to servlet security

• Supporting CORS is on the roadmap

– Cross Origin Resource Sharing

– Provide ability to invoke REST API via Javascript in the browser


Examples

• Examples will use an open source tool called curl

– https://curl.haxx.se/

• curl is a command line tool that can be used to make HTTP Requests

https://curl.haxx.se/


Examples - Get a Location using curl

• If a user wants to retrieve a Location entity curl -u <userName>:<password> http://host:port/GC3/api/sdo/location?id=<LOCATION_GID> [-o

</PATH/FileName.json>]

-u <userName>:<password> User Credential

http://host:port/GC3/api/sdo/location?id=<LOCATION_GID> URI for working with Location entity

[-o </PATH/FileName.json>] Where to store resulting JSON


Examples – Location JSON


Examples - Update a Location using curl

• If the user makes changes to the JSON file they can update the Location curl -d @</PATH/FileName.json> -H 'Content-Type:application/json' -u <userName>:<password> [-w

"%{http_code}\n"] -X POST http://host:port/GC3/api/sdo/location?id=<LOCATION_GID>

-d @</PATH/FileName.json> Path to JSON file to upload

-H 'Content-Type:application/json' Specify Content Type

-u <userName>:<password> OTM User Credential

[-w "%{http_code}\n"] Write out HTTP Response code when done

-X POST Specify HTTP Method to invoke

http://host:port/GC3/api/sdo/location?id=<LOCATION_GID> URI for working with Location entity


Documentation – Entity Link

• Lists all Entities

• Links to XML Schema showing fields


Documentation - XML Schema Definition

• Shows the fields associated with the Entity

• Shows data type for each of the fields

• Includes definition of child records


Documentation – Oracle Help Center

• Accessible on http://docs.oracle.com

• Describes how to get started

• List of APIs

– Supported operations

– Fields and objects

– Responses

http://docs.oracle.com/


Documentation - Oracle Help Center








Best Practices

• Start with a GET Request

– Understand the JSON format, especially for child records

• Understand the Transaction Codes for child records

– NP (No Persist) , I (Insert) , CD (Cascade Delete)

– While editing a child record if you modify a primary key field you need to perform a Delete and Add.

• When updating records send back all fields for top level entity

– Only need to send back the children that are being acted upon


Examples – Equipment Type JSON


Questions?

26

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 27

Technology

OTM and REST APIs