OData or GraphQL? The Best Tech for Developing an API Is Neither or Both!

Tribes throughout history have led to some of the most nonsensical decisions in human history. From the bloodiest days of the French Revolution to the current UK Brexit impasse. As a man from the North of England of working-class descent, and working in the liberal hotbed of West London for an American software company, I am a member of more tribes than most. What I have learned from many years in business and software development is that tribalism and stringent belief in almost anything is a recipe for disaster. One person’s love of Taylor Swift is not trumped by another’s love of the Foo Fighters. Both are acceptable musical tastes, right and proper for their intended audience or tribe. Not better, not noble, not more worthy, just collections of notes and melodies arranged in different orders.

By extension, as a software developer tasked with developing an API for interoperability and integration, don’t think about what is “best.” Like the music of Taylor Swift, “best” is a subjective principle. When developing an API, it is better to think about who consumes your API and how they will consume it, rather than purely on the features and benefits of a particular technology. Think about the platform or language you develop on, and how difficult it would be to build an API that presents data that adheres to either standard. Know your audience and understand the limitations of your technology and the maturity of the product you are developing. This will allow you to choose the most appropriate technology to use for your API.

Of course, knowledge is power and we need to objectively look at the capabilities of OData and GraphQL, and think about which API protocol your audience would prefer to consume.

OData

OData (Open Data Protocol) is an OASIS standard that defines the best practice for building and consuming RESTful APIs. OData provides a rich query language with capabilities for sorting, filtering, querying and reducing fields in the output of the API. It is strictly RESTful and expects to be delivered in conjunction with best REST practice. Not to get into yet another “tribal” discussion but what is REST and what it isn’t is a much-debated subject. Suffice to say that OData expects that your API will be heavily URI-centric and support standard REST operations such as GET, PUT, POST and DELETE. Due to its REST focus, mature specification, caching, stateless nature and extensive language support, services built on the OData standard should scale efficiently.

For transparency, Liferay, the company I work for, uses OData in conjunction with the OpenAPI standard to power our headless CMS API, known as the Headless Delivery API v1.0. In fact, we use the technology to power other API’s as well. Specifically, we use the Apache Olingo Library for mapping our entities to OData entities and converting OData queries into our Java OSGi service calls. In many ways, Liferay’s headless APIs are OpenAPI OData hybrids.

Liferay OpenAPI call in Postman with OData filter for Category ID

OData Capabilities and Strengths

1. Server-side implementation which can be implemented in most programming languages, with a high number of publicly available libraries.
2. A strict standard that is well documented and clear to implement against.
3. Good performance, being stateless and following REST principles. Scales horizontally easily.
4. Most programmers are familiar with REST, therefore, it is easier for them to use a REST-based framework.
5. Allows sending query strings with special conditions and filters using a documented OData syntax.
6. Supports Delta Feeds, a documented standard way of providing a client-specific (or near client-specific without being stateful) link, which, if called, will only provide new entries in an array.
7. Discoverable with a metadata URI.
8. Using HATEOAS, it is possible to solve an often-cited complaint with OData: that it doesn’t support versioning. The argument of OData not supporting versioning or field deprecation is moot, in that it is extremely easy to develop around this problem.
9. Data joins and relationships are supported by the concept of “relationships,” though relationships will often require multiple calls since the relationship is defined in URI within the response.
10. Entities are defined as part of the URI, which technically results in multiple calls/round trips to the API, this is more work for the developer but may be by design since static URI are easier to cache and therefore scale more easily.

An OData API is a good fit when you know that consumers of your API will come from a broad group of developers of different technologies, often with an enterprise slant. OData is a simpler concept and has a simpler definition for queries than GraphQL, which are powerful enough to meet most use cases. It is relatively simple to combine standard REST parameters with OData to support developers with varying levels of query complexity, from simply calling a URI, to complex selects. If as an organization I want to control the data produced by the API but don’t want unlimited data queries for performance reasons, OData presents an attractive option as a strong RESTful standard with an advanced feature set.

GraphQL

Facebook created a beautiful thing in GraphQL, a single URI mapped to a web service that allows you to have an API capable of meeting the most complex data requirements your customers demand. Providing you can scale it and have the time to implement what your customers wish to query, I see no reason why you would not implement a GraphQL API. It is most certainly not RESTful, but does that really matter?

GraphQL Capabilities and Strengths

• Like OData, there are a multitude of libraries for implementing, discovering and querying GraphQL.
• A single endpoint is a big plus factor for GraphQL in that it couldn’t be more simple to define to a consuming developer. A developer only needs two things: a URI and the knowledge that an API follows the GraphQL standard.
• Supports sorting, joins, relationships, selects, reduced data, versioning, deprecation, pagination and more from a single request/response round trip.
• Supports “Subscriptions,” similar but more powerful than Delta Feeds in OData.
• Supports functions, arguments, mutation, aliases, fragments, directives, unions, interfaces and all statically typed languages. In essence, GraphQL is a self-contained query and implementation language which is arguably more powerful than OData.

Having espoused the benefits of GraphQL, would I implement a GraphQL API for my customers? That depends on a few factors:

• Is my API a be-all and end-all for my organization, does the richness of my API directly influence the success of the business? This question allows me to ascertain required budget; the larger my budget the more likely I am to produce a GraphAPI, since it is the gold standard in terms of query capability.
• Believe it or not, the demographic of my API consumer might also color my judgement. If I want a catch-all API designed to suit a broad range of consumers regardless of age, skill and technology preference, I might go with the simpler OpenAPI or OData, or perhaps even a combination of the two. However, if my audience is younger, JavaScript-orientated, and possibly consumers of other GraphQL APIs like the Facebook Graph API, then I might play to that market and develop in GraphQL.
• The technology I use to implement the API will also play a huge factor as the syntax for GraphQL both in implementation and query is closer to JavaScript and Node than to other languages. There is anecdotal evidence that GraphQL does not play well with existing ORM engines in Java, for instance. I would need to feel secure that my development team had the requisite data structure and algorithm skills to best deliver what GraphQL promises in a scalable fashion. Once again, I would be looking at how greenfield my project is, especially within a Java-centric organization. All else being equal and catering to a young API consumer audience proficient in GraphQL, I would probably take the plunge and develop with that standard.

In conclusion, GraphQL has the zeitgeist and is in most circumstances the more powerful query language, but it can be expensive to implement and is not RESTful. Maybe you don’t care if it isn’t RESTful, and that’s OK. OData is very RESTful and has a lower learning curve for consumers of your API if they don’t know the query syntax. However, what matters most is who your consumer is and what the fastest, most cost-effective way you can delight that consumer is. Both OData and GraphQL have the power and simplicity to delight your target tribe. Finally, there are cases where implementing either technology would be akin to using a sledgehammer to crack a nut. Much can be achieved by just going the OpenAPI route or rolling whatever you like while sticking to a RESTful standard of your own making. There are many ways to keep your tribe happy.