Mastering Drupal 10/11 JSON:API for Decoupled Frontends

Problem: Exposing Drupal Content to a Headless Frontend

When building a decoupled application, the backend must deliver content in a machine‑readable format without custom controller code. Drupal’s core JSON:API module already offers RESTful endpoints, but many teams hesitate to use it because of uncertainty about how to enable, query, and secure the API.

Thesis: JSON:API is a ready‑made, secure, and performant API layer for Drupal 10/11

By enabling the module, crafting efficient queries with filters, sorting, and sparse fieldsets, and configuring view permissions, you can expose only the data your frontend needs while keeping the system’s cache and access control intact.

1. Enable JSON:API (Drupal 10/11)

JSON:API ships with Drupal 10/11, so the module is already present. Verify its status with:

drush pm-list --status=enabled | grep jsonapi

If you see it listed, it’s enabled. If you’re on a fresh install or have disabled it, enable it with:

drush en jsonapi -y

After enabling, test the base endpoint:

curl -I https://example.com/jsonapi
HTTP/2 200
Content-Type: application/json; charset=utf-8

A 200 response confirms the module is operational.

2. Crafting Efficient Queries

JSON:API follows the JSON:API spec, supporting standard query parameters:

• filter – restrict by field values
• sort – order results
• page[limit] – limit items per page
• fields – sparse fieldsets to reduce payload
• include – embed related resources

Concrete example: retrieve the five most recent published articles with only the title, body, and creation date.

GET https://example.com/jsonapi/node/article?filter[status]=1&sort=-created&page[limit]=5&fields[node--article]=title,body,created

Explanation of parameters:

• filter[status]=1 – only nodes where status is published (1)
• sort=-created – descending order by created timestamp
• page[limit]=5 – return at most five items
• fields[node--article]=title,body,created – include only these three fields in the node--article resource object

Resulting JSON is concise, reducing bandwidth and parsing time for the frontend. Test the query with curl and verify the data array contains exactly five nodes and the expected fields.

3. Securing Endpoints

JSON:API respects Drupal’s view permissions. By default, anonymous users cannot view content unless the View published content permission is granted. To restrict access further:

• Use drush role:perm to assign View published content only to specific roles.
• Install jsonapi_extras for granular control over which fields and relationships are exposed.
• Write a custom access controller if you need to hide content based on custom logic.

After permission changes, clear the cache to ensure the new rules take effect:

drush cr

4. Performance Trade‑offs

While JSON:API eliminates the need for custom endpoints, certain query patterns can degrade performance:

• Deep nested includes – each include triggers a separate database load; large trees can hit memory limits.
• High page limits – fetching hundreds of nodes in one request causes large entity loads and longer response times.
• Verbose responses – without sparse fieldsets, the payload can be several megabytes, stressing network and client parsing.

Mitigation strategies:

• Limit page[limit] to a reasonable number (e.g., 20–50).
• Use fields to return only the data required by the front‑end.
• Leverage Drupal’s HTTP cache tags in responses; configure a reverse proxy (Varnish, CDN) to cache based on Cache‑Tags and Cache‑Max‑Age headers.

5. Actionable Closing

1. Enable JSON:API – run drush en jsonapi -y and confirm the endpoint.
2. Define view permissions – only grant View published content to roles that need API access.
3. Write efficient queries – always use filter, sort, page[limit], and fields to keep payloads small.
4. Test responses – use curl or Postman to verify data and HTTP cache headers.
5. Monitor performance with Drupal’s Performance page or external APM tools; adjust limits or caching policies as needed.

By following these steps, you can confidently expose Drupal content to a headless frontend, ensuring the API is secure, efficient, and maintainable.