1Overview

End User License Agreement

This guide is intended for REST API software developers with customers or system implementors. While the content includes a reasonable overview of REST concepts, the assumption is that the audience understands REST, HTTP communication, response codes, and related topics.

Restful Web Services

Representational State Transfer (REST) is a web standards-based architecture utilizing the HTTP protocol for data communication. RESTful web services are a light weight, scalable, and maintainable way to allow web-based system-to-system communication, irrespective of the respective application platforms (interoperability).

RESTful web services use HTTP methods in combination with a Universal Resource Identifier (URI) to implement the REST architecture. For reference, a URL is a type of URI. This combination allows consumers to interact with application data via a set of controlled, stateless, and idempotent methods.

OCWMS has had REST API’s prior to update 18C, however they were not designed to provide fine grained access. These legacy API’s continue to be available. Once all the functionality provided by these API’s are incorporated into the newer APIs, the legacy ones will be retired with sufficient notice. The new APIs also adhere to RESTful practices better and simplify some of the data encoding requirements.

HTTP Requests

RESTful web services are built on top of the HTTP protocol, which carries some important implications. First, each request is stateless. This means that each request is independent of any other requests and the request itself must contain all relevant data to fulfill the request. Second, certain types of requests should be idempotent; making identical requests should yield the same result on the server. This is a safety measure that also provides consistency. For example, when reading data the same request should always yield the same result assuming the resource’s state on the server has not changed between requests.

HTTP Methods

The APIs may utilize the following five HTTP methods in order to provide users with Create-Read-Update-Delete (CRUD) functionality. Note that not all APIs support all methods.

GET

Return a read-only representation of the selected resource(s) in the response body.

HEAD

Read-only check for resource existence and/or modification. Does not return a response body.

POST

Create resources or submit data to be processed by a resource operation.

PATCH

Modify existing resource(s).

DELETE

Remove/deactivate existing resource.

URI Format

The lgfapi URI structure is broken down into several components.

In general, lgfapi URIs following the following schema:

The first portion of the URI (protocol, domain, environment, and app) is consistent with the URL of the environment’s UI accessed via a web browser. The remaining pieces after “lgfapi” are specific to the lgfapi and designate the version and path to any child modules and/or resources.

Versioning

Lgfapi requires a version number in all URIs. The format is “v#’, starting with “v9” as the first release. New versions are created only for major releases of the OCMWS application, not for minor versions. For example, the release of OCWMS 9.0.0 included the lgfapi v9 release, but there will not be a new lgfapi version number with the release of OCWMS 9.0.1. However, the APIs will continue to be updated with new features and improvements along with the minor releases of OCWMS.

The purpose of version control is to give customers some ability to remain on their current integrations until they can complete any changes required to handle the newest lgfapi version. It is strongly encouraged that all customers use the latest version of lgfapi. Version control is a tool to assist with upgrades and testing, it is not meant to be used in production for extended periods of time. The previous versions of lgfapi will unavoidably become out of sync with newer versions of OCWMS, and eventually will no longer be compatible. Oracle will not make changes to previous versions of lgfapi in order to maintain expired functionality or compatibility. Therefore, it is always in the best interest to use the latest version. New API versions are planned approximately once a year. Older API versions will be supported approximately one year after a newer one is released.

lgfapi Modules

Lgfapi contains modules that can be utilized by customers. These are groupings of functionality that may have their own formats and requirements. For example, lgfapi’s “entity” module is designed to allow customers to examine and interact with OCWMS business resources from outside the application.

Resource Path

The final component to the URI is the resource path. This may take many different forms depending on the HTTP method and any module-specific requirements.

Optional Trailing Slashes

A trailing slash at the end of and lgfapi URIs is optional and does not affect functionality.

Login and Authentication

Since each HTTP request is stateless, every request requires information to authenticate the user.

Lgfapi supports several types of user authentication:

• BasicAuth – Classic username and password.
• OAuth2 – A token based authorization framework.

Application Permissions

Making a request to lgfapi not only requires user authorization, but also one or more of the CRUD application-level permission to access the supported HTTP methods. These are configurable in the user’s group-level permissions.

• “lgfapi_read_access” – GET, HEAD
• “lgfapi_create_access” – POST
  Note: this access is also required in order to run resource operations.
• “lgfapi_update_access” – PATCH
• “lgfapi_delete_access” – DELETE

It’s recommended to create dedicated user(s) with appropriate lgfapi permissions and different facility/company eligibility to protect the integrity of your data. For instance, it is safe to give users read access but may not be appropriate to grant them permission to create or modify data.

The legacy API permission, “can_run_ws_stage_interface”, has been replaced by the new permission, “lgfapi_update_access”. This permission now applies to both lgfapi and the legacy APIs. For legacy API’s, this is the singular permission required to access all APIs. For lgfapi, this is one of several new permissions used to control user access.

Data Input Methodology

Lgfapi allows for transmission of data in one of two ways, based on the HTTP method being used.

GET/HEAD

These read-only HTTP methods allow the user to pass additional information about the request in the URI. This data is sent as key-value pairs and starts with a question mark (“?”) at the end of the main URI. This section of the URI is known as the “query string”. Each key-value pair is known as a “parameter”. It is used to provide additional information to the resource. Parameters are delimited by an equals sign (“=”), and multiple parameters are delimited by an ampersand (“&”). The order of the parameters does not matter.

URL Encoding

In general, URIs only allow ASCII values, however there are specific cases like with internationalized domain names (IDN) where non-ASCII characters may be used in the domain name. For the purposes of communicating data using query string parameters in lgfapi, you cannot directly send non-ASCII (unsafe) characters. Also, some characters like spaces, “=”, and “&” have a specific meaning when sent in the query string section of the URI and are reserved. In order to handle unsafe characters and to distinguish between data and reserved characters that have special meaning in a URI, the URI must be “URL Encoded”. This encoding replaces non-ACII and reserved characters parameter data with ASCII equivalents. This is also known as “Percent Encoding” since each unsafe character is replaced with a value starting with percent sign (“%”). All parameter values should be URL encoded to ensure correct transmission.

For example, the query string: “foo=Mañana” is URL encoded as “foo= %20Ma%C3%B1ana”. A URI cannot have a space so that is encoded to the value “%20”. The Spanish letter “ñ” is not a valid ASCII value and is encoded as “%C3%B1”. Once the data reaches the server, it is decoded back to the original characters. The key portion of each parameter is determined by the application and therefore will never contain unsafe characters.

See https://www.w3schools.com/tags/ref_urlencode.asp for more information.

It is possible to repeat the same parameter within the query string. However, lgfapi will only observe the final occurrence of the parameter in order to obtain a value. For example, given the query string “?code=A&code=B”, the interpreted value of the “code” parameter will be “B”. The “A” value is discarded. There is no use case for transmitting repeated parameters as the desired result is achieved through other module-specific query string mechanisms.

POST

A POST request is used to pass data to the server similar to pressing a “Submit” button on a web page to submit form data to the server. In the context of lgfapi, when making a POST request, the user is passing data to either create a resource or invoke a resource operation, such as cancelling an order. Unlike GET and HEAD requests, POST allows for text data to be passed in the free-form body of the request. Request body data must be in a supported format (JSON or XML) and follow the required structure of the API being invoked.

Content-Type HTTP Header

This HTTP header is required when using a method like POST, PATCH, and DELETE that allow transmitting data in the body of the request. It describes the data format so it can be correctly parsed server-side. Lgfapi supports JSON and XML input and therefore requires one of the two content-type values:

• application/json
• application/xml

The Content-Type “application/x-www-form-urlencoded” is not supported in lgfapi, but is still required for legacy OCWMS APIs.

Content Encoding

By default, lgfapi will use UTF-8 to decode the request body as this handles the majority of characters for languages supported in OCWMS. However, for situations where customers choose to use a different encoding, it can be specified in the Content-Type header’s optional “charset” parameter:

Content-Type: application/json; charset=latin-1

Lgfapi will use the provided charset to decode the request body data. It is up to the customer to ensure that their data is properly encoded using the desired charset before transmission to lgfapi. Failure to do so may result in incorrect characters or an inability to process the request.

It is also important to note that this only applies to the encoding of the request body and does not apply to the encoding used in any response body data from lgfapi.

Request Body Data – Repeated Keys

Lgfapi does not restrict users from repeating data in the request body for a single request. Rather, it will use only the final occurrence in the body when processing the request.

For example, if one were to send a request with the key “code” multiple times in the same request body:

{

“code”: “A”,

“code”: “B”

}

The value used to process the request will be “B”. “A” is ignored and is never used. There is no lgfapi use case for needing to pass repeating data in the same request.

Request Body List Formatting

JSON and XML data follow language standards except for the case of lists of items in XML. This is a unique concern for XML since there is no standard methodology for how to handle lists whereas JSON supports lists by default.

XML Lists

A list of items in XML is represented by the wrapper tag, followed by a wrapper for each item’s value with the special tag name “list-item”. For example, representing a list of serial numbers under the wrapper “serial_nbr_list”, in JSON is represent as:

{

“serial_nbr_list”: [ “SN1”,

“SN2”

]

}

The equivalent XML list would be represented as the following. Note the use of “list-item” for each entry in the list to allow for correct parsing.

<serial_nbr_list>

<list-item>SN1</list-item>

<list-item>SN2</list-item>

</serial_nbr_list>