JSON, REST, and other data formats

When one software system communicates with another, both sides need to agree on how the information will be organized. The sender needs a way to package data into a transferable format, and the receiver needs to recognize that format and reconstruct the information correctly.

For modern web APIs, one of the most common formats is JSON.

The good news is that you already know how to read its main structures because JSON is built from labeled values, lists, strings, numbers, booleans, and null, the same shapes you encountered in Module 3.

What is JSON?

JSONConcept · lights on your mapJSONJavaScript Object Notation, a text-based data format for representing and exchanging structured information: objects with keys and values, lists, strings, numbers, booleans, and null. Not limited to JavaScript; used by applications in nearly every language. stands for JavaScript Object Notation.

Despite the name, JSON is not limited to JavaScript, and applications written in Python, Java, Go, Ruby, and many other languages use it.

JSON is a data format used to represent and exchange structured information.

But it is not programming logic and does not contain functions, conditionals, or loops. It describes data in a form that both people and software can read.

Consider this JSON response from a payment API:

Reading the JSON object

The opening and closing curly braces show that the response contains an object.

Inside the object are labeled values. Each label is called a key, and the information associated with it is the value.

The first key-value pair is: "id": "ch_8802"

The key is "id", and its value is the string "ch_8802".

The ID gives the payment a unique name that can be used in later API requests. For example, GET /charges/ch_8802 might retrieve information about that specific charge.

Numbers in JSON

The next value is: "amount": 1450

The amount is a number rather than a string because it is not surrounded by quotation marks.

In many payment systems, money is represented using the currency’s smallest common unit. For U.S. dollars, 1450 may represent 1,450 cents, or $14.50.

Representing money this way helps software avoid certain rounding problems that can occur when decimal values are stored using floating-point numbers.

This is a common design choice, but APIs can represent money in other ways as well, so the API’s documentation should explain what the number means and which currency it uses.

Booleans and null

The next value is: "paid": true

This is a boolean, and it indicates that the payment succeeded.

In JSON, booleans are written in lowercase: true and false

The next field is: "failure_reason": null

null means that no value is present.

In this example, there is no failure reason because the payment succeeded. The field exists, but it currently has no value.

This is a useful and intentional use of null: the response has a place for a failure reason, but there is nothing to report.

Nested JSON objects

The final field contains another object: "card": { "brand": "visa", "last4": "4242" }

The larger payment object contains a smaller card object, a pattern called nesting. Data structures can contain other structures inside them.

The card object contains:

• A string identifying the card brand
• A string containing the final four digits of the card number

"4242" is stored as a string rather than a number because the digits are an identifier. The software will not perform arithmetic with them.

Real API responses often contain many nested objects and lists. A customer object might contain a list of orders, and each order might contain a list of items.

The structures can become large, but they are built from the same few recognizable shapes.

JSON lists

JSON can also represent ordered collections using square brackets. For example: { "drinks": ["latte", "mocha", "tea"] }

The value of "drinks" is a list containing three strings.

A list can also contain several objects:

If you can identify objects, lists, keys, strings, numbers, booleans, and null, you can understand the basic structure of almost any JSON message.

JSON has strict rules

JSON resembles structures used in many programming languages, but it has its own syntax rules.

In standard JSON:

• Keys must be enclosed in double quotation marks.
• Strings must use double quotation marks.
• Booleans are written as true and false.
• An empty value is written as null; a missing field is simply left out.
• Comments are not allowed.
• Items are separated using commas.

This is valid JSON: { "paid": true, "amount": 1450 }

This Python dictionary looks similar, but it is not standard JSON: { "paid": True, "amount": 1450 }

Python uses True with a capital letter, while JSON uses lowercase true.

Software libraries handle these conversions automatically, but recognizing the distinction will help you understand what you are looking at.

JSON in API requests and responses

JSON can appear in both directions of an API conversation.

A client may send a JSON request body: { "drink": "latte", "size": "large" }

The server may return a JSON response: { "order_id": 1042, "status": "confirmed" }

A header such as Content-Type: application/json explains that the body uses JSON.

The receiving software reads the JSON and turns it into data structures it can use internally.

What is REST?

RESTConcept · lights on your mapRESTRepresentational State Transfer, a common architectural style for organizing web APIs: model the system as resources at URL paths (/orders, /orders/1042), acted on with the standard HTTP methods. The predictability lets engineers make reasonable guesses about unfamiliar APIs. stands for Representational State Transfer.

REST is an architectural style commonly used to organize web APIs, and a REST-style API generally models important parts of a system as resources. A resource might be:

• An order
• A customer
• A payment
• A product
• A message

Each resource is associated with a URL path. For example, /orders may represent the collection of orders, while /orders/1042 may represent one particular order.

HTTP methods then communicate the general action the client wants to perform.

Reading REST-style endpoints

A REST-style orders API might include:

This predictability is one of REST’s advantages. Once an engineer understands how one part of the API is organized, they may be able to make reasonable guesses about other parts.

However, these are conventions rather than automatic rules, and the API’s designers decide which endpoints exist and what each one does.

A DELETE endpoint might cancel an order without permanently erasing its data. A POST endpoint might perform an action rather than create a traditional resource.

The API documentation provides the authoritative meaning.

REST and JSON are different concepts

REST and JSON frequently appear together, but they are not the same thing.

REST describes an approach to organizing an API.

JSON describes a format for representing data.

A REST API can return JSON, but it could also use XML, plain text, images, or another format.

Similarly, an API can use JSON without following REST conventions.

A useful distinction is: REST helps organize the menu. JSON helps package the information being exchanged.

What is XML?

XMLRecognition — just know it existsXMLExtensible Markup Language, another structured text format that uses tags rather than braces and brackets. Widely used before JSON became dominant; still important in enterprise systems, banking, government, and document formats. stands for Extensible Markup Language.

It is another structured text format used to represent data.

An XML version of a payment might look like:

XML was widely used for software communication before JSON became dominant in many modern web APIs, and it remains important in established enterprise systems, banking, government, publishing, document formats, and certain industry standards.

You do not need to learn XML syntax deeply. Recognize it as another structured data format that uses tags rather than JSON’s braces and brackets.

What is CSV?

CSVRecognition — just know it existsCSVComma-Separated Values, table-like information as lines of plain text: a header row of column names, then one row per line. Ideal for spreadsheet exports and simple tabular data; not suited to deeply nested structures. stands for Comma-Separated Values.

CSV represents table-like information as lines of plain text:

CSV is useful for:

• Exporting spreadsheet data
• Moving tabular information between systems
• Producing reports
• Working with large, simple datasets

Unlike JSON, CSV does not naturally represent deeply nested structures. It is best suited to rows and columns.

CSV also does not carry strong information about data types. The value 1042 appears as text in the file, and the receiving software decides whether to interpret it as a number, identifier, or something else.

What is parsing?

ParsingRecognition — just know it existsparsingReading information in a particular format and identifying its structure, turning JSON text into structures a program can work with. If the syntax is invalid, parsing fails; “failed to parse” means the text was malformed. is the process of reading information in a particular format and identifying its structure.

When software receives a JSON response, it initially receives a sequence of bytes or text. A JSON parser reads the braces, brackets, keys, values, and punctuation and turns them into structures the program can work with.

If the JSON contains invalid syntax, parsing may fail.

For example, this is missing a comma: { "drink": "latte" "size": "large" }

A person may understand what was intended, but a strict JSON parser will reject it.

Serialization and deserialization

When software prepares an internal data structure for transmission, it must convert that structure into a format such as JSON, and this process is called serializationConcept · lights on your mapserializationConverting an internal data structure into a transferable format, such as an object becoming JSON text. The outbound half of an API exchange; deserialization is the return trip..

For example, an application might convert an internal order object into the JSON text { "drink": "latte", "size": "large" } before sending it.

When the receiving system converts the JSON back into its own internal data structures, the process is called deserializationConcept · lights on your mapdeserializationConverting a transferable format back into an internal data structure, such as JSON text becoming an object again. The inbound half of an API exchange; serialization is the outbound one..

The round trip is:

Internal structure → serialization → transferable format

Transferable format → deserialization → internal structure

Serialization does not always produce text, and some systems use compact binary formats. In the case of JSON, however, the serialized representation is text.

What is GraphQL?

GraphQLRecognition — just know it existsGraphQLAn API approach in which the client sends a query describing exactly the data fields it wants returned, an alternative to REST’s fixed endpoints. More client control over response shape, with its own complexity around queries, caching, permissions, and performance. is another approach to building APIs.

With a REST-style API, the server defines endpoints that return particular representations of resources.

With GraphQL, the client sends a query describing the fields it wants.

For example, a client might ask for only an order’s ID and status rather than receiving every available field, which can give clients more control over the shape of the response.

GraphQL also introduces different complexity involving query design, caching, permissions, and server performance. It is not automatically better or worse than REST.

For now, recognize it as: an API approach in which clients describe the data fields they want returned.

Seeing the complete API exchange

Imagine the coffee backend sending a payment request.

The coffee backend deserializes the response, checks whether "paid" is true, stores the payment ID, and continues processing the order.

The complete flow combines several ideas:

• HTTP carries the request and response.
• REST helps organize the API’s resources and endpoints.
• JSON represents the data inside the bodies.
• Serialization and deserialization translate between internal structures and transferable data.

The mental model to remember

JSON is a text-based format for representing structured data using objects, lists, strings, numbers, booleans, and null.

REST is a common style for organizing web APIs around resources, paths, and HTTP methods.

JSON and REST often appear together, but they solve different problems.

XML is another structured data format that uses tags.

CSV represents table-like rows and columns as plain text.

Parsing means reading formatted information and identifying its structure.

Serialization converts an internal data structure into a transferable format. Deserialization converts it back.

GraphQL is an API approach in which the client requests a particular shape of data.

You should now be able to read a JSON API response, identify its data types and nested structures, and understand how REST helps make API endpoints more predictable.