Open Data Protocol

The PROLIN Power Server REST API is based on the Open Data Protocol (OData) version 4.0.

Definition

“The Open Data Protocol (OData) is an OASIS standard that defines the best practice for building and consuming RESTful APIs. OData helps to focus on the business logic without having to worry about the approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc. In addition it also guides about tracking changes, defining functions/actions for reusable procedures and sending asynchronous/batch requests, etc.

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the API’s, enables the creation of powerful generic client proxies and tools. Some of them can help to interact with OData even without knowing anything about the protocol.”

Source: http://www.odata.org

OData 4.0 Conformance Notes

The REST API implements OData 4.0. The following behaviours differ from, or go beyond, the 4.0 specification.

Context URL of an expanded navigation property

When a navigation property is expanded without a nested $select or $expand, the @odata.context URL lists it with empty parentheses:

GET http://myserver:5181/odata/ServiceRequests?$expand=Caller

"@odata.context": "http://myserver:5181/odata/$metadata#ServiceRequests(Caller())"

This is the OData 4.01 notation. OData 4.0 leaves such a property out of the list ($metadata#ServiceRequests). The OData library the REST API is built on writes the 4.01 notation in every response. Do not rely on the select list of the context URL to tell which properties were expanded.

Removing a member from a collection

OData 4.0 names the member to remove with the $id query option:

DELETE http://myserver:5181/odata/ServiceRequests(3101097999)/Workorders/$ref?$id=http://myserver:5181/odata/Workorders(281486108328022)  HTTP/1.1

The REST API also accepts the key of the member in the path, which is the OData 4.01 form:

DELETE http://myserver:5181/odata/ServiceRequests(3101097999)/Workorders(281486108328022)/$ref  HTTP/1.1

Clients that must also work with other OData 4.0 services should use $id.

Requests that declare OData 4.01

Requests with an OData-Version: 4.01 or OData-MaxVersion: 4.01 header are accepted. Their bodies are still read with the OData 4.0 JSON format, so control information needs the odata. prefix: write @odata.id, not @id. The response currently repeats the requested version in its OData-Version header, but its content follows OData 4.0. Send OData-MaxVersion: 4.0 to receive responses that declare the version they conform to.

Specification

For the full OData 4.0 specification, refer to the official online documentation:

OASIS Documentation

Back to top