Scroll
JSON:API vs. core's REST module
TL;DR
Choose REST if you have non-entity data you want to expose. In all other cases, choose JSON:API.
Slightly more nuanced:
- Core's REST module allows for anything (any format, any logic, any HTTP method) and extreme configurability. Powerful but complex and hence relatively brittle.
- JSON:API focuses on exposing Drupal's biggest strength (entities/data modeling) in a coherent manner. Simple yet sufficiently powerful for most use cases.
Feature matrix
| Feature | JSON:API | REST | Remark |
|---|---|---|---|
| Entities exposed as resources | ✔️ | ✔️ | REST: need to configure this per entity type. JSON:API: everything exposed by default. Both: respect entity access. |
| Custom data exposed as resources | ✔️ | Write custom @RestResource plugins. JSON:API only supports entities. | |
| Getting individual resources | ✔️ | ✔️ | |
| Getting lists of resources | ✔️ | kinda |
REST: need to configure a view, and set up a "REST export" display. |
| Paginating list of resources | ✔️ | The additional modules like the Pager Serializer are needed. | REST: not supported! REST export views return all resources. |
| Filtering list of resources | ✔️ | kinda |
REST: only if you create an exposed filter for every field, and every possible operator |
| Sorting of resources | ✔️ | ||
| Includes/embedding | ✔️ | Only in HAL+JSON | |
| No unnecessary wrapping of field values | ✔️ | Both the HAL normalization and the default normalization (and hence all formats) suffer from exposing exactly the in-memory PHP data structures that Drupal uses, causing painful DX for consumers. JSON:API simplifies the normalization of single-cardinality and single-property fields. | |
| Ability to omit fields consumer does not need | ✔️ | ||
| Consistent URLs | ✔️ | ||
| Consumer can discover available resource types | ✔️ | ||
| Drupal-agnostic response structure | ✔️ | REST: the HAL normalization in theory is void of Drupalisms, but in practice it isn't. | |
| Client libraries | ✔️ | ||
| Extensible spec | WIP | ||
| Zero configuration | ✔️ | REST: each @RestResource plugin definition is available to be exposed, but must be configured to be exposed. For each, you must select the allowed formats, allowed authentication providers and optionally even allowed HTTP methods. JSON:API: all entities are exposed automatically, entity/field access is respected, all installed authentication providers are allowed automatically. |
More information
See the rationale for adding the JSON:API module to Drupal core, and the module architecture rationale.
Article from Drupal Documentation.