OData Provider Overview¶

OData¶

OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs. OData APIs are easy to consume. OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools.

URL Structure Illustrated

Figure 1 - URL Structure of two OData Queries

More information available at: http://www.odata.org/documentation/

IFS OData Provider¶

IFS OData Provider exposes IFS business entities and business logic through OData endpoints. It is based on Apache OLingo, a java library that implements the OData protocol and is used for the functions below:

Parsing of requests into syntax trees
Metadata validation
Parsing of HTTP request content
Generation of JSON results

IFS OData Provider with the help of Apache Olingo do the translation between the OData protocol and the underlying IFS Business Logic.

FndODataProvider

Figure 2 - FndODataProvider

OData Response¶

After processing a request the OData Provider responds using any valid HTTP response code along with the relevant OData Response Body.

OData Response Codes¶

The HTTP response codes align with the standard HTTP response classes. For example an error occurring due to incorrect request from the client will fall into the HTTP 4XX series, while errors which occur due to server side errors will fall into the HTTP 5XX series. Successful request fall into the category of HTTP 2XX.

Some examples for client side errors

HTTP 404 (Not Found) will be returned when the requested resource is not found. e.g. trying to retrieve a Customer Order (using keys) which is non existing.
HTTP 400 (Bad Request) will be returned for malformed requests including incorrect URLs, bad headers, malformed request body.
HTTP 405 (Method Not Allowed) will be returned if you try to do an incorrect HTTP verb against an endpoint. e.g.. trying to do a GET on an OData Action.
HTTP 423 (Locked) can occur when the request resources is locked. This can happen for Documents and Media which are blocked by the Virus Scanner since it's currently been scanned or since a threat had been detected.

Some examples for server side errors

HTTP 500 (Internal Server Error) An error has occurred at the server (Middle-tier or Database). Further information can be obtained by looking at the Response body
HTTP 501 (Not Implemented) A request has been made for functionality that the OData Provider does not support
HTTP 503 (Service Unavailable) can occur due to two reasons.
When a service endpoint has changed after it was initial loaded. If so the response body will say MI_MODIFIED_ERROR as the status code. The request can be retried immediately.
An outage of the service (e.g. restart), should be resolved automatically after a small period of time.
HTTP 504 (Gateway Timeout) can occur if your request is not completed within the allocated time. See Request Timeout

Please note the following

A debug response (odata-debug=json) will always return HTTP 200 even though the underlying request has failed. The correct response code can be seen in the response body
Certain database side validation failures will still result in a HTTP 500 error.

OData Response Body¶

The OData Response body data is dependent on the resource which has been requested and the operation performed.

For Error Responses the structure of the error is as below.

{
    "error": {
        "code": "MAIN ERROR CODE",
        "message": "MAIN ERROR MESSAGE",
        "details": [
            {
                "code": "DETAIL ERROR CODE",
                "message": "DETAIL ERROR MESSAGE"
            }
        ]
    }
}

For some server side errors like Database Errors, the details section will have additional information on the errors like the Oracle error which occured.

For errors due to issue in the request, the Main Error Code will say REQUEST_ERROR.

Changes to Error Response Codes and Response Body after IFS Cloud 23R1 GA¶

Prior to IFS Cloud 23R1 GA, errors due to client request had the HTTP 500 error code. But with 23R1 GA the behavior was aligned to return HTTP 4XX errors. To revert back to the previous error codes the HTTP header IFS-Legacy-Response-Codes can be set to true. However, it highly recommended to update your clients to the new error codes.