Comparing OData, JSON API, GraphQL, and OpenAPI: When to Choose Each

Question: I have used OData extensively in my career, and few colleagues suggest moving to JSON API or GraphQL because they are not Microsoft‑related. I have little experience with these query languages. As far as I know OData is a mature standard used by Salesforce, IBM, Microsoft. Why switch to JSON API and/or GraphQL? Are there real benefits? Are they new standards? Changing a public API without clear advantage seems pointless.

Answer: OData is a specification similar to JSON API; both describe standard protocols for creating and consuming RESTful APIs. GraphQL is a completely different API design approach that defines a different way to query API resources.

OData

Developed by Microsoft since 2007 and standardized by OASIS. The latest version V4 has been submitted to ISO/IEC JTC 1 for international standard approval. Companies in the technical committee include CA Technologies, Citrix, IBM, Microsoft, Progress, Red Hat, SAP and SDL.

There are many libraries for popular programming languages – .NET, Java, JavaScript, PHP and Ruby. The specification allows dynamic resources and provides a service document that lists all API endpoints for client discovery, as well as a metadata document that describes the schema.

JSON API

JSON API was first drafted by Yehuda Katz in May 2013, derived from the implicit JSON transport defined by Ember Data’s REST adapter. The current stable version is 1.0. The specification applies to most programming languages, both client‑side and server‑side.

JSON API supports HATEOAS through link attributes in JSON documents. Other features include pagination, sorting, filtering and relationships. The JSON documents generated by JSON API servers are very verbose, containing many nested attributes.

GraphQL

Developed by Facebook since 2015. The specification is still a working draft. It is popular among React enthusiasts and is often used together with React or Vue.js. A similar newer project is Falcor.

Although GraphQL uses HTTP, it is not considered REST but an alternative to it. Instead it uses a query/response model within a single (virtual) JSON document. This model can be more convenient for developers, but its advantages over REST are debatable and the ecosystem is still immature.

For completeness I also include OpenAPI, which, while not strictly an API protocol, is a language‑agnostic standard for describing and defining APIs.

OpenAPI (formerly Swagger)

Developed as part of the OpenAPI Initiative and the Linux Foundation, with support from Google, Microsoft, IBM, SAP, Oracle, eBay and PayPal. The current version is 3.1.0. Implementations exist for most programming languages, along with many tools such as web UI generators.

The biggest benefit of using standards like OpenAPI is the surrounding tooling – generators for API documentation pages, client SDK code generators, etc.

This standard is probably the most widely used today for API declaration, documentation and code generation, and is also supported by cloud providers such as Amazon Web Services in their API gateways.

In summary, OData and JSON API are JSON‑based formats that add context and features (e.g., links) around data, GraphQL is a completely different method for querying and mutating JSON data, and OpenAPI is a standard way to declare and document any RESTful API.

Personal Opinion

As you can see, there are many RESTful specifications rather than a single universal standard. I agree with xumix’s view that they all suffer from “nothing to invent here” syndrome. The benefit of choosing any of them is small, especially for small‑to‑medium projects. The important thing is to build a consistent and well‑documented API.