OData FAQs: Why Should REST API Developers Use OData?

Why use OData? Who is adopting OData? In this quick FAQ, learn about features of OData like FHIR, RFC, IETF, Security, JSON, batch requests and pagination.

In this blog, we compiled a set of FAQs on OData (the Standard for a REST API) based on our interactions with a diverse group of API developers across various events and meetups.

The exponential growth of SaaS applications has led to an explosion of REST APIs. As of today, there are almost 18,000 APIs registered on the ProgrammableWeb, and research shows that around 40 new APIs are being added every week. This means that a developer today will be spending most of his or her time learning new APIs instead of building the application itself. To solve this problem, Microsoft founded the OData standard for building REST APIs.

OData (Open Data Protocol) defines a set of best practices for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the various approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc. We are proud to serve on the OData Technical Committee (in fact, we were the first member of this committee) along with other technical giants such as CA and Citrix.

Most recently, I presented at a local meetup — TRI REST — to introduce the audience to OData. You can find my presentation here. This meetup was especially interesting because it helped me understand how developers evaluate a new standard like OData. We had a great discussion around this standard for REST. Here is a brief excerpt of that discussion:

Why should I use OData?

As APIs continue to explode, each organization exposes its own unique REST/SOAP/Bulk APIs for consuming their data. And some of them also come up with their own unique query language such as ROQL (Oracle Service Cloud), SOQL (Salesforce), etc. This makes it difficult for an enterprise and its development team to be able to learn and code against all these different APIs.

This is where OData is very useful. OData advocates a standard way of implementing REST APIs that allows for SQL-like querying capabilities using these RESTful APIs. OData is essentially SQL for the web built on top of standard protocols — HTTP, JSON & ATOM — while leveraging the REST architecture style. Learn through code samples how OData can simplify your life in this tutorial blog: Marketo REST API vs Eloqua REST API vs OData

Which companies are adopting OData?

Some of the developers were curious to know whether Microsoft was the only company pushing OData. However, they were surprised to realize that OData has been adopted by a lot of technologies and companies including SAP, IBM, Salesforce, Tableau, Databoom, Progress, Red Hat and Dell. The OData ecosystemhas a list of some of its consumers and producers and the slide below is a list we’re tracking, but it’s growing faster than we can keep up with.

How is FHIR related to OData?

FHIR, or Fast Healthcare Interoperability Resources Specification, is a standard for exchanging healthcare information electronically. In order to make FHIR truly interoperable, it is recommended that systems use the rules specified by OData specification for the $search parameter. Further, FHIR also uses OAuth in order to establish a trusted relationship with the client for an extra layer of security. Read more about this here.

Is OData compliant with the Internet Standards?

Yes, OData is an OASIS standard and has been recently ratified as an ISO standard. It is also based on a lot of the RFC standards from the IETF (Internet Engineering Task Force). Here are some of the RFC standards it uses:

RFC7240, RFC7230, RFC7231, RFC7232, RFC7235 — HTTP 1.1 Specifications (Note: RFC2616, RFC2617 have been obsoleted and replaced by these latest specifications)

RFC5023 The Atom Publishing Protocol

RFC2119 Keywords for use in RFCs to Indicate Requirement Levels

RFC5789 Patch Method for HTTP

RFC3629 UTF-8

RFC7159 JSON (Note: RFC4627 has been obsoleted and replaced by this specification)

RFC 3986 URI

RFC 2046 Multipurpose Internet Mail Extensions (MIME)

Is OData susceptible to SQL Injection or other security attacks?

OData is a query language like SQL with which you can query anything that is exposed by the model. Like SQL, if the application only wants to expose certain parts of the model, the application will need to provide those restrictions.

As for security attacks, this will depend on the implementation. I am not aware of any security flaws that are specific to the OData specification. Since OData is exposed as a REST API, the implementation must guard against security vulnerabilities like any other REST API.

From a Progress DataDirect product perspective, our hybrid connectivity servicesfollow the OWASP guidelines for protecting against known security vulnerabilities.DataDirect Cloud is also subject to routine security scans and penetration testing both by internal resources and independent external resources.

How can I manage the JSON version according to the schema?

The JSON that is returned from a query is defined by the model. If the model changes, the JSON in the response will change. In the OData 4.0 spec the CSDL syntax that is used to define the OData model does not have a way to assign a version to a model. The intent was that once an OData API was published at a given URL, its model would not change. If there was a change to the model, then a new (possibly versioned) URL would be provided.

However, there were enough requests for versioning the model that a SchemaVersion annotation was added to the CSDL in the coming OData 4.0.1 specification. A specific version of the model can be requested with the SchemaVersion request header for OData 4.0.1

Can OData support batch requests like in an email?

OData supports batch requests. Batch requests allow grouping multiple operations into a single HTTP request payload. A batch request is represented as a Multipart MIME v1.0 message RFC 2046, a standard format allowing the representation of multiple parts, each of which may have a different content type (as described in [OData-Atom] and [OData-JSON]), within a single request.

Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service, located at the URL $batch relative to the service root. The batch request MUST contain a Content-Type header specifying a content type of multipart/mixed and a boundary specification as defined in RFC 2046.

What about pagination? Does pagination work for frequently changing content like Twitter?

OData is designed as a set of conventions that can be layered on top of existing standards to provide common representations for common functionality. To aid in client/server interoperability, this specification defines multiple levels of conformance for an OData Service, as well as the minimal requirements for an OData Client to be interoperable across OData services. For a minimum conformance, OData must support server-driven paging. Beyond that one could also apply client-side pagingthrough query options such as Orderby, select, skip, top, filter, expand and inlinecount.

This pagination is done on a per query basis. Typically if query capability is done on a streaming service like Twitter, then the query is done for a particular time slice. If there is more data in that time slice, then the data will be broken up into pages.

Does OData support procedures? Can we perform JOINs across Federated databases?

Yes, OData supports procedures. In RESTful APIs, there can be some custom operations that contain complicated logic and can be frequently used. For that purpose, OData supports defining functions and actions to represent such operations. They are also resources themselves and can be bound to existing resources. Further, OData does not preclude federating data from multiple sources.

Getting Started with OData

Now that you have learned enough about OData, you can get started with it by using our hybrid connectivity services. You can dive a little deeper into OData with our quick guide, or check out our short tutorial for help getting started and playing with OData. And in case you have more questions around OData…

Talk to an OData Expert

This content originally appeared on the Progress blog, by Nishanth Kadiyala. Looking for more great stories about technology and building tomorrow’s business apps? Check out the blog for more.