Building REST APIs with JSON
JSON reduces friction between systems by representing exchanged information in a form that maps directly onto native programming-language data structures.
The Data-Exchange Problem
When applications exchange data across the web, they need a representation that different systems can read and understand. XML served this purpose for decades, but developers found that parsing XML and extracting its data often required verbose and complicated code. JSON became the preferred alternative because its structure aligns more naturally with the way programming languages organize data.
JSON reduces friction between systems by representing exchanged information in a form that maps directly onto native programming-language data structures.
From JSON to Native Data
The central advantage of JSON is alignment. A JSON object can become a native object or dictionary in application code, while a JSON array can become a native list or equivalent structure. A built-in JSON parser performs this conversion in a single operation. After that conversion, the application accesses the received information using the same style of syntax it uses for other variables in its language.
Tracing a User Response
Consider a web service that sends a mobile application a user's name, email, and recent orders. The service can send these related pieces of information in one compact JSON structure. The mobile application receives the structure, parses it, and obtains a native object. The developer can then access the user's name as a property of that object and work with the orders as part of the same native structure.
The literal values in this example are illustrative. The structural pattern comes from the user-service scenario: named user information is grouped together, and recent orders are represented as a collection inside that structure. Once parsed, application code can use the resulting native object rather than manually interpreting the original text.
Why Less Parsing Code Matters
JSON's direct mapping reduces the amount of parsing and data-extraction code an application needs. A parser converts the received JSON into a native object or dictionary in one operation. The application can then access the needed values through that native structure. Compared with XML, this means fewer lines of translation code, fewer opportunities for bugs, and faster development.
| Concern | JSON | XML |
|---|---|---|
| Relationship to application data | Maps directly onto native data structures | Does not align as naturally with internal programming-language organization |
| Parsing and extraction | Requires significantly less code | Often requires more verbose and complicated code |
| Development effect | Fewer opportunities for bugs and faster development | More translation work between the format and application data |
The comparison explains why JSON is commonly chosen for application-to-application exchange.
Where XML Still Fits
JSON's dominance does not make XML useless. XML remains advantageous when self-description is critical. Its human-readable tags explicitly describe what each piece of data represents, so the format itself communicates meaning without depending as heavily on external documentation.
Word processors are an example of a context where XML remains valuable. A document can contain formatting, metadata, and content in a complex hierarchical structure that must be preserved exactly. XML's self-descriptive tags make the role of each element clear to people as well as machines. In this situation, the additional verbosity can be worthwhile because clarity of the document format matters more than minimizing parsing effort.
Designing the Default Choice
For a new API or communication channel between services, JSON is generally the practical starting point. Its direct relationship with native data structures makes the receiving code easier to write and maintain. The choice reflects a broader software-design principle: prefer tools that reduce friction between systems and let developers spend more time solving business problems than converting data formats.
Common mistake Assuming JSON is automatically the right choice for every exchange.
What it looks likeChoosing JSON for a complex document format even when self-description and exact preservation are the primary requirements.
Why it failsJSON is not perfect for every use case. XML retains advantages when the format itself must communicate meaning clearly.
Do this insteadStart with JSON for application-to-application exchange, but check whether the system has a specific reason to prioritize XML.
Common mistake Treating parsing as a separate translation project after receiving JSON.
What it looks likeDesigning extra conversion layers even though the JSON parser already produces a native object or dictionary.
Why it failsThe practical value of JSON is its direct mapping to native data structures.
Do this insteadUse the parsed native structure directly for data access.
Common mistake Evaluating a format only by whether machines can read it.
What it looks likeIgnoring how understandable the format must be to people working with complex documents.
Why it failsXML's self-descriptive tags can be valuable when human-readable meaning and document structure are critical.
Do this insteadConsider both parsing simplicity and the communication needs of the data format.
Check Your Design Choice
You are designing a service that sends user information and a list of recent orders to a mobile application. Explain why JSON is a strong default for this exchange. Then describe one requirement that could make XML the better choice instead.
Hints
- Start with the relationship between JSON structures and native application data.
- Connect direct mapping to parsing effort, code size, and opportunities for bugs.
- For the XML case, focus on self-description and complex document structure.
Choosing a Format for Two Exchanges
Compare a user-and-orders exchange with a complex word-processing document.
- 1Identify the first exchange
The user-and-orders exchange is application data moving between systems. JSON structures map directly onto native objects, dictionaries, and lists.
- 2Evaluate implementation effort
JSON can be parsed into native data in one operation, so extraction requires less code and creates fewer opportunities for bugs than XML-based processing.
- 3Identify the second exchange
A word-processing document contains formatting, metadata, and content in a complex hierarchy that must be preserved and understood.
- 4Apply the format principle
JSON is the practical default for the user-and-orders exchange. XML can be advantageous for the document because its tags are self-descriptive and clarify what each element represents.
Choose JSON for the ordinary application-data exchange. Consider XML when self-description and complex document preservation are more important than minimizing parsing complexity.
Key Takeaways
- 1JSON is widely preferred because its structures map directly onto native programming-language data structures.
- 2A JSON parser can convert received data into a native object or dictionary in one operation, simplifying later access.
- 3Compared with XML, JSON usually requires less parsing and extraction code, reducing complexity and potential bugs.
- 4XML remains useful when self-description is essential, especially for complex document formats such as word processors.
- 5The practical default is JSON for application-to-application exchange, unless a specific requirement justifies another format.
At a glance
- JSON became the preferred application-data format because it aligns with native programming-language structures.
- This alignment reduces translation work, parsing code, and opportunities for bugs.
- JSON is a strong default for REST APIs and other exchanges between applications.
- XML remains advantageous when self-descriptive structure is critical, including complex document formats.