DrupalRX Field Guide
Enterprise Drupal diagnosis, architecture, and implementation notes.
Tutorials

JSON:API Sparse Fieldsets and Includes: The Performance Guide Nobody Wrote

Sun, 03/15/2026 - 13:00 admin
JSON:API Performance Sparse Fieldsets Includes Headless Drupal

Most headless Drupal performance problems don’t start with Drupal.

They start with API requests.

Specifically:

  • Requests that return too much data
  • Requests that include too many relationships
  • Requests that fetch information nobody actually needs

Developers often focus on:

  • Redis
  • CDNs
  • Database tuning
  • Infrastructure scaling

before addressing the far simpler question:

Why are we sending so much data in the first place?

One of the most underutilized features in Drupal JSON:API is sparse fieldsets.

One of the most abused features is includes.

Understanding both can dramatically improve:

  • Response times
  • Payload size
  • Frontend performance
  • Cache efficiency

This article explains how.

The Problem Most Teams Don’t See

Consider a typical request:

  • http id="4ol74h" /jsonapi/node/article

Seems harmless.

But what is Drupal actually returning?

Potentially:

  • Title
  • Body
  • Author
  • Revision metadata
  • Created date
  • Changed date
  • Status
  • Relationships
  • Media references
  • Taxonomy references
  • Internal identifiers

And more.

The frontend may only need:

  • Title
  • Path
  • Hero image

Yet Drupal still returns everything.

Multiply that across:

  • 20 articles
  • Homepage requests
  • Mobile applications

and performance begins suffering.

What Are Sparse Fieldsets?

Sparse fieldsets allow clients to request only specific fields.

Instead of:

  • http id="hzjlwm" /jsonapi/node/article

You can request:

http id="fd8g1j" /jsonapi/node/article ?fields[node--article]=title,path,field_image

Now Drupal only returns:

  • Title
  • Path
  • Hero image

Nothing else.

This creates immediate benefits.

Why Sparse Fieldsets Matter

Most developers focus on response time.

Sparse fieldsets improve much more than that.

Benefits include:

Smaller Payloads

Less data transferred.

Faster Serialization

Drupal builds smaller responses.

Faster Parsing

Frontend applications process less JSON.

Better Mobile Performance

Especially important on slower connections.

Better Caching

Smaller payloads cache more efficiently.

These gains compound.

The Hidden Cost of Over-Fetching

Many frontend teams adopt a mindset of:

Let’s request everything now in case we need it later.

This seems harmless.

It isn’t.

Example:

  • Homepage card component needs:

text id="e1cld8" Title Image URL

Instead the API returns:

text id="z3u5zm" Title Body Author Taxonomy Metadata Relationships Timestamps Images Status Revision data

Most of that information is discarded.

The user pays the performance cost anyway.

Includes: Powerful and Dangerous

JSON:API includes solve a legitimate problem.

Without includes:

  • Frontend requests:

text id="jlwm1k" Article

Then:

  • text id="1t3frc" Author

Then:

  • text id="7uhjdi" Image

Then:

  • text id="jbbz4e" Category

Multiple requests create latency.

Includes solve this by allowing relationship expansion.

Example:

  • http id="kw2y3d" ?include=field_author,field_image

Now everything arrives in a single request.

That’s useful.

Until it isn’t.

The Include Explosion Problem

This is where many projects go wrong.

Developers begin with:

  • http id="p5whyo" ?include=field_author

Then add:

  • http id="pn8r5f" ?include=field_author,field_image

Then:

  • http id="1w9l4m" ?include=field_author,field_image,field_tags

Then eventually:

  • http id="6o8wj0" ?include=*

At this point:

Payload size explodes.

Response complexity increases.

Serialization costs increase.

Frontend performance suffers.

The API becomes slower.

Includes Should Match UI Requirements

A useful question:

What is actually visible on this screen?

Not:

What might be useful later?

Example:

  • Article card displays:
  • Title
  • Hero image

Then include:

  • http id="mgn0dp" field_image

Nothing more.

If the author isn’t visible, don’t fetch it.

If taxonomy isn’t visible, don’t fetch it.

API requests should reflect UI requirements.

Relationship Depth Matters

Relationships can become surprisingly deep.

Example:

  • text id="uxczb7" Article ↓ Author ↓ Department ↓ Location ↓ Organization

Developers sometimes fetch the entire chain.

This creates large payloads and expensive processing.

Ask:

Does the current view really need all of this?

Often the answer is no.

Designing APIs Around Use Cases

One mistake I see frequently:

Teams design APIs around data availability.

Instead of:

What data exists?

Ask:

What does this screen need?

Examples:

Homepage

Minimal data.

Article Listing

Moderate data.

Article Detail Page

Full data.

Different pages should often have different request strategies.

Measuring Payload Size

Performance work should be measurable.

Track:

Payload Size

Response Time

Serialization Time

Frontend Parsing Time

Many teams focus exclusively on response time.

Payload size often reveals more useful information.

A 50KB response behaves very differently from a 2MB response.

Frontend Teams Share Responsibility

This is important.

Developers sometimes blame Drupal for slow APIs.

But frontend applications frequently contribute.

Examples:

  • Duplicate requests
  • Excessive includes
  • Missing caching
  • Over-fetching

Performance is shared responsibility.

Not a backend-only problem.

A Practical Strategy

For most headless Drupal projects, I recommend:

Step 1

Start small.

Request only required fields.

Step 2

Add includes intentionally.

Step 3

Measure payload size.

Step 4

Review frontend usage patterns.

Step 5

Optimize based on data.

Not assumptions.

Common Mistakes

Mistake #1

Never Using Sparse Fieldsets

You’re paying for data you don’t need.

Mistake #2

Using Include Everything

Convenience creates performance costs.

Mistake #3

Designing Around Database Structure

Design around user experiences.

Mistake #4

Ignoring Payload Size

Large payloads eventually become user experience problems.

Mistake #5

Assuming More Data Is Better

Usually it isn’t.

JSON:API Optimization Checklist

Sparse Fieldsets

  • Implemented?
  • Consistent?
  • Reviewed regularly?

Includes

  • Purposeful?
  • Necessary?
  • Measured?

Payload Size

  • Tracked?
  • Optimized?
  • Benchmarked?

Frontend

  • Duplicate requests eliminated?
  • Caching implemented?
  • Queries reviewed?

Architecture

  • API strategy documented?
  • Relationship depth reviewed?

Final Thoughts

Most JSON:API performance issues aren’t caused by Drupal.

They’re caused by request design.

Sparse fieldsets and includes give developers powerful tools for controlling API behavior.

Used properly, they can dramatically improve:

  • Performance
  • Scalability
  • User experience

Used carelessly, they can create the very performance problems teams later spend months trying to solve.

The goal isn’t requesting more data.

The goal is requesting exactly the data you need.

No more.

No less.

That’s where efficient API design begins.

Need Help Optimizing a Headless Drupal Platform?

DrupalRX helps organizations evaluate JSON:API performance, frontend integration strategies, content architectures, caching approaches, and headless Drupal implementations.

If your APIs feel slower than they should, start by examining the requests—not the infrastructure.

standard