Upload
prasad-chandane
View
938
Download
56
Embed Size (px)
Citation preview
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.
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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.
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Agenda
• Overview of REST and JSON
• Logistics Integration Methods
• Introduce the Logistics REST API
• Authentication and Authorization
• Examples
• Documentation
• Best Practices
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Overview of REST and JSON – JSON vs XML
http://www.pcmag.com/encyclopedia/term/56790/json
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Logistics Integration Methods
• Bulk operation methods
– WMServlet
– SOAP API
– Integration Cloud Service
• Use case for REST API
– Synchronous
– Building custom UIs
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Examples – Location JSON
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation – Entity Link
• Lists all Entities
• Links to XML Schema showing fields
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation - XML Schema Definition
• Shows the fields associated with the Entity
• Shows data type for each of the fields
• Includes definition of child records
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation – Oracle Help Center
• Accessible on http://docs.oracle.com
• Describes how to get started
• List of APIs
– Supported operations
– Fields and objects
– Responses
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation - Oracle Help Center
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation - Oracle Help Center
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation - Oracle Help Center
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Documentation - Oracle Help Center
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
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
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Examples – Equipment Type JSON
Copyright © 2015 Oracle and/or its affiliates. All rights reserved. |
Questions?
26
Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 27