The Schema.org Blueprints module builds content models based on Schema.org's specification for structured data. The generated Schema.org content models are understandable, shareable, and reusable by people, machines, and search engines. To share these content models, we need to expose our data using an API. This post will explore reasonable recommendations for exposing our Schema.org based content inside Drupal to decoupled front-ends and machines.
Currently, in the Drupal community there are two popular API specifications/web services implementations: JSON:API and GraphQL. JSON:API is included in Drupal core and GraphQL is built and maintained as a contributed module. To understand the current state of these different web services implementations, it helps to look back at the history of the decision to include JSON:API in Drupal core and why GraphQL is a contributed module.
In 2019, Dries Buytaert, Drupal's project lead, thoroughly compared REST vs JSON:API vs GraphQL. Dries summarizes the goal of the post.
In this blog post, we will compare REST, JSON:API and GraphQL. First, we'll look at an architectural, CMS-agnostic comparison, followed by evaluating some Drupal-specific implementation details.
Dries' conclusion led to the JSON:API module being added to Drupal core.
…JSON:API has outperformed its contemporaries. Its web standards-based approach, its ability to handle reads and writes out of the box, its security model and its ease of operation make it the best choice for Drupal core.
Philipp Melab, for Amazee Labs, wrote a thoughtful response re-examining the value of GraphQL even though it is not included in Drupal core.
One of Philipp's concerns about exposing Drupal data structure via JSON:API is that the API will contain a lot of Drupal'ism.
Information in Drupal might be accessible to arbitrary clients, but they still have to maintain a deep knowledge about Drupal data structures and conventions (entities, bundles, fields, relations…). You might be able to attach multiple front-ends, but you will never be able to replace the Drupal backend. So you reached the identical state of coupling as Drupal had for years by being able to run different themes at the same time.
Philipp ends his response by stating.
The real strength of GraphQL is that it allows us to adapt Drupal to the world around it, instead of having to teach everybody how it thinks of it.
The decision to include JSON:API into Drupal core is very sound. As a backend developer, I found implementing and tweaking Drupal's JSON:API to build an easy-to-understand API relatively simple and matter-of-fact. The Schema.org Blueprints JSON:API module creates JSON:API endpoints for only Schema.org types and properties which reduces the amount of Drupal'ism exposed via an API.
Conversely, I still feel overwhelmed trying to quickly understand how to build a GraphQL schema. My mistake when approaching GraphQL was starting with the Drupal GraphQL module, looking at how to implement the backend API, which is a bit complex. I should've first lookedat how easy it is for front-end developers to query GraphQL server. As I worked through the GraphQL's Queries and Mutations tutorial about how to query a GraphQL server, I saw how intuitive and easy it is for front-end developers to write GraphQL queries against a complete platform-agnostic GraphQL schema. The fact that GraphQL can have a platform-agnostic schema aligns better with the Schema.org Blueprints module goal of providing standardized and universal data. Still, I find it hard to recommend going all-in with GraphQL.
The fact that JSON:API is included in Drupal core and it is simpler to implement explains why the Drupal Next.js Startkit is using JSON:API. Of course, there is also support for GraphQL for the Next.js Drupal module.
What is my sound recommendation for using JSON:API and GraphQL with the Schema.org Blueprints module?
To build a decoupled but Drupal-aware front-end, it is easier to use JSON:API.
To build a decoupled platform agnostic front-end and API, it is better to use GraphQL.
For teams transitioning from a coupled to a decoupled Drupal architecture, use JSON:API
For teams seeking to build a complete decoupled backend with Drupal, use GraphQL.
There is always the option to use both JSON:API and GraphQL. JSON:API can be used to expose Drupal's content model to build decoupled pages and menus. For public facing APIs and more advanced functionality like building a dynamic interface, including interactive maps, GraphQL is a better fit. My final recommendation is to start with JSON:API with a gradual and long-term goal to move toward GraphQL.
This exploration into which API seems appropriate for the Schema.org Blueprints module highlights that we must establish more standardized content models and think about how we share our content.
What are your thoughts and experience with using JSON:API or GraphQL as the API specifications/web services for your Drupal website?