REST API Design Rulebook

Chapter 5. Representation Design

Message Body Format

A REST API commonly uses a response message’s entity body to help convey the state of a request message’s identified resource. REST APIs often employ a text-based format to represent a resource state as a set of meaningful fields. Today, the most commonly used text formats are XML and JSON.

XML, like HTML, organizes a document’s information by nesting angle-bracketed^[37] tag pairs. Well-formed XML must have tag pairs that match perfectly. This “buddy system” of tag pairs is XML’s way of holding a document’s structure together.

JSON uses curly brackets^[38] to hierarchically structure a document’s information. Most programmers are accustomed to this style of scope expression, which makes the JSON format feel natural to folks that are oriented to think in terms of object-based structures.

Warning

This chapter’s examples favor the JSON format. However, JSON does not support invisible comments or wrapping long string values, which made it difficult to keep some of the examples well-formed. The malformed examples are noted as such inline.

Rule: JSON should be supported for resource representation

As a format for data exchange, JSON supports lightweight and simple interoperation: it does its job. Today, JSON is a popular format that is commonly used in REST API design, much like bell-bottomed jeans were fashionable in the 1970s. JSON borrows some of JavaScript’s good parts and benefits from seamless integration with the browser’s native runtime ...