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 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 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.
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.