What is the difference between OData, JsonAPI, GraphQL?

by

OData is a similar specification to JSON API. Both of them describe a standard protocol for creation and consumption of RESTful APIs. GraphQL is a totally different approach to API design and specifies a different way of querying API resources.

  • OData: Designed and developed at Microsoft since 2007, standardized by the OASIS consortium. The latest version V4 is submitted to ISO/IEC JTC 1 for approval as an international standard. Companies on the technical committee (TC) include CA Technologies, Citrix, IBM, Microsoft, Progress, Red Hat, SAP and SDL.

    There are a number of libraries for popular programming languages – .NET, Java, JavaScript, PHP and Ruby. The spec allows dynamic resources and there’s a service document which lists all API endpoints for clients to discover. Additionally, there’s a metadata document describing the schema.

  • JSON API: JSON API was originally drafted by Yehuda Katz in May 2013. This first draft was extracted from the JSON transport implicitly defined by Ember Data’s REST adapter. The current stable version of the spec is 1.0. The JSON API spec is implemented for the majority of programming languages, for both the client and server sides.

    JSON API supports HATEOAS through the link property in the JSON document. Other features include pagination, sorting, filtering and relationships. The JSON documents produced by JSON API servers are very verbose with lots of nested properties.

  • GraphQL: Developed at Facebook since 2015. The specification is still a working draft. It’s quite popular among React fans and is mainly used in combination with React or Vue.js. Similar to GraphQL is Falcor, which is also relatively new.

    While GraphQL makes use of HTTP, it is not considered REST, rather, an alternative to REST. Instead it makes use of a query/response model into a single (virtual) JSON document. This new model is somewhat nicer for developers to work with, but its benefits over REST are debatable. Given its young age, the ecosystem has yet to mature.

For the sake of clarity and completeness, I’ll include OpenAPI to the list, although it is not exactly an API specification. That can be confusing to some people. The OpenAPI standard is a language-agnostic standard for describing and defining APIs. Your API can follow one of the above standards (excluding GraphQL) and also be documented using OpenAPI 3, for example.

  • OpenAPI (a.k.a. Swagger): Developed as part of the OpenAPI Initiative and the Linux Foundation. Supported by big tech companies like Google, Microsoft, IBM, SAP, Oracle, Ebay and PayPal. The current version of the spec is 3.1.0. There are implementations for the majority of programming languages, as well as lots of additional tools like web UI generators, etc.

The best thing you get with specs like OpenAPI is the tooling around them – generators for API documentation pages, generators for client SDK code, etc.

This standard is probably the most commonly used today for API declaration, documentation and code generation. It is also supported by cloud providers like Amazon Web Services in their API Gateway.

In summary, OData and JSON API are both JSON data formats which add context and features (e.g. links) around your data, GraphQL is a totally different new way to query and mutate JSON data, and OpenAPI is the standard way to declare and document any RESTful API.

My personal opinion:

As you can see, there are quite a few RESTful specs out there, rather than a single universal standard. I agree with xumix here – they all seem to suffer from the “Not Invented Here” syndrome. The benefits of choosing any of the above are small, especially if your project is small or medium sized.
Does it matter which specification your API implements? Probably not much. Just focus on building a consistent and well-documented API.

Leave a Comment