Starting with Drupal 8.7, JSON:API comes bundled with Drupal core. Until then, it was a contributed module developed almost entirely by Mateu Aguiló. However, Dries (the creator of Drupal and its Benevolent Dictator for Life) saw its potential and, after comparing it with other alternatives, decided to integrate it into the core and allocate more resources to it.
What is JSON:API?
JSON:API is a format that works over HTTP. It defines how the client (usually the browser) should request or edit data from the server, and how the server should respond to those requests.
The main goal is to optimize HTTP requests — both in quantity and size.
JSON:API was created as an alternative to REST API, which presented a series of challenges:
- You need to define an endpoint for each resource.
- It’s not possible to modify from the client side which fields are returned. This means that if more fields are needed, the REST API developer has to add them — and if not all fields are used, bandwidth and processing time are wasted transferring unnecessary data.
- If a page needs data from more than one resource, multiple calls or custom endpoints must be made.
In response to these issues, two main alternatives emerged: GraphQL and JSON:API. Both of these specifications solve the problems mentioned above — you can read more in Dries’ post.
In my experience, after trying both technologies, the difference is that JSON:API is simpler — and simplicity is always a good thing. For something relatively new, the available documentation on Drupal.org is quite good, though as always, it could use more examples.
What Does JSON:API Format Look Like?
Here’s an example of a resource of type article:
1// ...2{3"type": "articles",4"id": "1",5"attributes": {6"title": "Rails is Omakase"7},8"relationships": {9"author": {10"links": {11"self": "/articles/1/relationships/author",12"related": "/articles/1/author"13},14"data": { "type": "people", "id": "9" }15}16}17}18// ...
How to Enable JSON:API in Drupal
Remember that JSON:API is included in core starting from Drupal 8.7. If you’re using an earlier version, you can install it as a contributed module. Just enable it — there’s no additional configuration required.
Then, visit the /jsonapi URL on your domain. For example, we’ll use drupaldemo.omitsis.com, where we have a Drupal site updated to the latest version using the Umami installation profile.
So, if you go to drupaldemo.omitsis.com/jsonapi, you’ll see all available resources — and the best part is that they’re navigable by clicking. Anyone familiar with GraphQL might miss GraphiQL’s powerful interface, but JSON:API is much simpler and more straightforward.
For example, if you have a content type called “recipe,” click on it and you’ll be taken to https://drupaldemo.omitsis.com/jsonapi/node/recipe, which is the endpoint for that content type.
Can You Filter, Remove, Add Fields, and Include Relationships with JSON:API?
Short answer: Yes, you can.
Long answer: It deserves an entire post on its own — the second part of this introduction. Meanwhile, you can check all of this in the official documentation.
And if you’d like to implement JSON:API in your next company project, get in touch with us — we’ll be happy to help.