This document synthesizes a comprehensive overview of enhancements made to the REST (Representational State Transfer) API services within the Transportation and Global Trade Management platform. The enhancements span the introduction of new services, expansion of resource coverage, performance improvements, and advanced integration capabilities.
Foundational REST Services and Evolution
The platform has seen a significant evolution in its REST API, moving from an initial query-only service to a comprehensive API supporting full Create, Read, Update, and Delete (CRUD) operations across a wide range of business objects.
The Modern OTM/GTM REST Service (18C)
The introduction of a new, modern REST Service established a lightweight, standardized data communications API. This foundational service was designed to conform to Oracle's REST API standards, providing a robust platform for future enhancements.
Initial Capabilities:
- Resource Retrieval: Ability to retrieve single resources using either GID or XID.
- Collections and Filtering: Support for retrieving collections of resources, with capabilities for ordering, paging, and filtering using existing Saved Query definitions.
- Flexible Responses: Options to retrieve summary or expanded responses. The
fieldsquery parameter limits returned attributes, while theexpandquery parameter includes attributes for sub-resources. - Sub-Resource Access: Ability to drill-down and retrieve only sub-resources of a root resource (e.g., retrieving only the reference numbers for an order release).
- Hypermedia Links: Responses contain URI links to sub-resources, facilitating easy navigation of resource content.
- Standardized Naming: A revised list of supported objects follows a standard naming convention.
Initially, this service was limited to data query operations and did not support persistence (create, update, delete).
Evolution of Persistence
Following its introduction, persistence capabilities were incrementally added to the REST API, expanding its utility beyond simple data retrieval.
| Release | Enhancement | Description |
|---|---|---|
| 19C | Order Release | Introduced basic synchronous Create and Update operations for the Order Release resource. |
| 20A | Shipment & sShipUnits | Added POST (Create) and PATCH (Update) methods for the Shipment resource, its child tables, and the sShipUnits resource. |
| 20B | Order Base | Extended POST and PATCH operations to the Order Base resource. |
| 21A | Document Resources | Enabled POST, PATCH, and DELETE methods for Document resources. |
| 25A | Parent/Child Updates | Enhanced the PATCH method to update both parent and child resources in a single request via the glog.fusion.cil.restapi.config.includeChildren property. |
Expanded Resource Coverage and Operations
The scope of the REST API has been continuously expanded to cover more business objects and enhance operations on existing ones.
Newly Supported Resources
| Resource | Operation(s) | Description |
|---|---|---|
| Shipment Group | GET (Read-only) | Provides read access to Shipment Group resources, including their Secondary Charge details. |
| Commodity Power Data | CRUD | Full Create, Read, Update, and Delete operations are supported for the Commodity Power Data object, enabling bulk loading. |
| Service Provider | GET, POST (Create/Batch Create) | Offers comprehensive GET access and robust POST capabilities for creating Service Provider objects, including associated locations and contacts. |
| Various Power Data Objects (21A) | GET | A major expansion added read-only access to a wide array of power data and configuration objects, including accessorialCodes, accounts, agentActions, calendars, contactGroups, equipmentGroups, incoterms, locations, rateOfferings, rateRecords, scacs, and many more. |
Enhancements to Existing Resources
- Trade Item Structure: The API was updated to include Value Qualifier and corresponding Value fields on both the Trade Item Structure and its components, facilitating better data integration.
- Shipment: The Waybill Date field was added to the Shipment REST API. This date can be used instead of the shipment start date for rating purposes. User Defined Attribute fields (numbers 11-20, dates 11-20) were added.
- Shipment Stop: Additional User Defined Attribute fields (numbers 11-20, dates 11-20) were added.
- External Statuses: An optional feature enables Create, Update, and Delete operations via REST for External Statuses and their values on numerous business objects.
- Order Release, Order Release Line, Ship Unit: Additional User Defined Attribute fields (numbers 11-20, dates 11-20) were added and are included in the respective REST APIs.
New API-Driven Features and Integrations
The REST API serves as the backbone for several powerful new features and external integrations.
Outbound REST Notifications
The platform's REST capabilities were extended to support sending outbound business objects. This feature uses the same REST resource formats available for inbound messages.
- Communication Method: A REST notify communication method is available in the Send Interface Transmission and Send Integration Agent Action actions.
- Agent Action: The SEND REST EVENT agent action can be configured within an Automation Agent to trigger outbound REST messages based on system events.
Ad-hoc Restricted Party Screening
A dedicated REST API endpoint allows external systems to perform ad-hoc restricted party screening.
- Request: The request can contain party details (name, address) and the Service Preference ID to use for screening.
- Response: The response can be configured to return the original request data, a link to the screening results, or the full results.
Data Export API
A REST API is available for data export, providing a programmatic way to extract data.
- Object-Based Export: Data can be exported on an object basis, which includes the parent object and all its related child objects.
- Formats: The export supports CSV (default) and a single JSON file format.
- Processing Limits: Synchronous (30s, 1MB) and Asynchronous (180s, 1GB) options available.
SharePoint Online Integration
The platform can integrate with SharePoint Online for document management using the Microsoft Graph (MS Graph) API. This allows users to add, view, modify, and delete documents stored in SharePoint from within the OTM/GTM user interface.
Configuration: Requires setting up an external system with specific MS Graph API URLs, such as https://graph.microsoft.com/v1.0/drives.
Querying and Data Retrieval Enhancements
Significant improvements have been made to enhance the flexibility and efficiency of data retrieval via the REST API.
Advanced Querying on Child Resources
The API supports querying parent resources based on the attributes of their child resources (one level deep). This allows for more precise data filtering without needing to retrieve and process large datasets.
Example: Searching for locations where a reference number value ends with "TEST":
/logisticsRestApi/resources/v2/locations?q=refnums.locationRefnumValue ew "TEST"Response Customization with Out JSON Profile
The Out JSON Profile feature provides granular control over the structure and content of GET request responses for parent resources.
- Configuration: Profiles are created under Business Process Automation > Power Data > Integration > Out JSON Profiles and assigned to an External System.
- Capabilities:
- Define which child resources and specific fields to include in the response.
- Choose whether to return the full details of child resources or just URI links.
- Create multi-level profiles for nested resources.
- Invocation: The profile is specified in the API call using the
outJsonProfileIdparameter.
Response Clarity and Efficiency
To reduce redundancy and improve the clarity of API responses, a change was made to hide primary keys (GIDs) and parent GIDs by default. This is controlled by the glog.fusion.cil.restapi.config.hidePks and glog.fusion.cil.restapi.config.hideParentPks properties, which are now set to true by default as of release 21A.
Performance, Stability, and Monitoring
Several features have been introduced to improve the performance, stability, and monitorability of REST API services.
| Feature | Description | Benefit |
|---|---|---|
| REST API Definition Cache | An optional feature that maintains an in-memory cache for frequently used REST API resource definitions. | Improves system operation and response times for common API calls. |
| Optimize REST Finder | An optional feature that logs the total number of columns retrieved by a REST API query. | Provides insights into resource usage, helping administrators set limits to prevent performance degradation from overly broad queries. |
| Historical Metrics for REST | Extends the Historical Metrics platform to capture count-based statistics for REST services. It tracks SYNC REST and ASYNC REST operations for Read, Create, and Delete Counts, as well as Batch Counts and Custom Action Counts. | Enables proactive monitoring of API usage and performance trends over time. |
Authentication, Security, and Configuration
Enhancements in authentication and configuration provide greater security and control over REST API interactions.
- OAuth 2.0 Support: The BuildNotifyMessageWorkflow was extended to support REST client capabilities using OAuth 2.0 and custom HTTP Header Profiles for application/xml and text/xml content types, in addition to application/json.
- HTTP Basic Authentication Control: Properties such as
glog.security.basicAuth.useCase.apiallow administrators to control the use of HTTP Basic Authentication for API-related use cases. - Enhanced Workbench Security: The Enhanced Workbench relies on REST calls for data access. Consequently, users require the REST – Workbench Access Control List (ACL) entry to use its functionalities.
- XID Validation: The property
glog.ui.validateXid.suppresscan be used to suppress the validation of external IDs (XIDs) for data submitted via REST, providing flexibility for integration scenarios. - Mobile App Access: Users of the progressive web application (PWA) Mobile App require the Mobile Web Application REST - View ACL for access.
Implementation Considerations
When implementing these REST API enhancements, consider the following best practices:
- Review and configure the appropriate security settings based on your organization's requirements.
- Utilize the monitoring capabilities to track API usage and performance.
- Leverage the Out JSON Profile feature to optimize response payloads for your specific use cases.
- Consider implementing rate limiting and throttling to ensure system stability under high load.