Skip to content

Chapter 5 of 7

Data Formats, Content Negotiation, and Hypermedia

JSON has become the de facto response format for REST APIs thanks to its compactness, readability, and near-universal language support. While XML and other formats are still possible, most modern APIs standardize on JSON for both request and response bodies. Rather than fix the format at design time, the more expressive approach is content negotiation: the client sends an Accept header such as Accept: application/json, and the server picks the best representation it can produce. This lets a single API serve multiple consumers with different format needs and gives a clear upgrade path if a new representation becomes desirable later, without breaking clients that pinned to the old format.

A few related techniques refine how data crosses the wire. Partial responses let the client request only the fields it needs, typically through a query parameter like ?fields=name,email, which reduces bandwidth and CPU on both ends for large resources. Compression with gzip or Brotli is also commonly applied at this layer to shrink payloads further. Hypermedia, in the form of HATEOAS, raises the abstraction by embedding links inside responses so that clients can navigate related resources and available actions dynamically—for example, a payment resource might include links to its refund, receipt, and dispute endpoints rather than forcing the client to construct URIs.

HATEOAS is one of the most powerful and least adopted aspects of REST: when implemented, it lets the server evolve URIs and add new relationships without breaking clients, because clients follow links rather than constructing paths themselves. The trade-off is response size and the complexity of describing link relations, which is why many APIs settle on returning a few stable, conventional links per resource instead of a fully hypermedia-driven interface.

All chapters
  1. 1Foundations of REST
  2. 2HTTP Methods and Their Semantics
  3. 3URI Design and Resource Modeling
  4. 4Status Codes and Error Handling
  5. 5Data Formats, Content Negotiation, and Hypermedia
  6. 6Performance Patterns
  7. 7Security, Authentication, and Cross-Cutting Concerns

Drill it

Reading is not remembering. These come from the Rest API Design deck:

Q

What does REST stand for?

REST stands for Representational State Transfer, an architectural style for designing scalable web APIs using standard HTTP protocols.

Q

What is a resource in REST API design?

A resource is any entity or information that can be named and addressed via a URI, such as a user, order, or document, represented in a format like JSON.

Q

What are the core principles of REST?

REST follows principles like client-server separation, statelessness, cacheability, uniform interface, layered system, and optionally code-on-demand.

Q

What does statelessness mean in REST?

Statelessness requires that each request from a client contains all necessary information for the server to process it, without relying on server-stored session...