Working with APIs and JSON Responses
JSON uses two main structures: objects (key-value pairs in curly braces) and arrays (ordered lists in square brackets).
From API Response to Data
When a web API sends information, that information needs a structure that both people and programs can interpret. JSON, which stands for JavaScript Object Notation, is a lightweight, text-based format used to encode and exchange data across the web. Its central idea is simple: data is organized with objects, arrays, and values.
JSON has two main structures: objects, which hold key-value pairs, and arrays, which hold ordered lists.
A useful way to begin reading a JSON response is to ask two questions: What kind of structure am I looking at, and what does each value represent inside that structure? Curly braces identify an object, while square brackets identify an array.
Objects and Key-Value Pairs
A JSON object describes named properties. Each property has a key and a corresponding value. The key identifies what the value means. For example, a key such as name can identify a person's name, while a key such as email can identify email-related information. In JSON, object keys must be strings written in double quotes.
The value associated with a key is not limited to text. JSON values can be strings, numbers, booleans, null, objects, or arrays. This allows one object to describe a single entity while also containing more detailed structures inside it.
Reading a Contact Object
Interpret an object describing contact information.
Find the outer structure: The outer structure is an object because it is represented with curly braces.
List the keys: The object has the keys name, phone, and email.
Classify the values: The value for name is a simple string. The values for phone and email are themselves objects.
Read the nested meaning: The phone object contains type and number. The email object contains hide. Related details are grouped under the property they describe.
The outer object represents one contact, and its nested objects organize phone and email details.
Arrays as Ordered Collections
A JSON array is an ordered list represented with square brackets. Arrays are useful when the data is a collection of similar items rather than the named properties of one entity. The order of values is part of how the collection is represented.
When you encounter square brackets, read the contents as members of one ordered collection. Unlike an object, an array does not organize its members primarily through named properties. The important information is that the values belong to the collection and appear in a particular order.
| Structure | Visual boundary | Main purpose | Contents |
|---|---|---|---|
| Object | Curly braces | Named properties of a single entity | Key-value pairs |
| Array | Square brackets | Collection of similar items | Ordered values |
Nested Data Hierarchies
JSON becomes especially useful when structures are nested. An object can contain another object or an array, and an array can contain objects. This creates a hierarchy: a value may be simple, or it may open into another structure that contains more values.
To read nested JSON, move from the outside toward the inside. First identify the outer object or array. Then identify the value associated with the relevant key, or the item occupying the relevant position in an array. If that value is another object or array, continue reading its contents at the next level.
Following Two Levels of Nesting
Determine how to interpret a value stored inside the phone property of a contact object.
Start at the contact object: The outer object represents the contact and contains named properties.
Follow the phone key: The phone key points to another object rather than to a simple value.
Read the inner keys: Inside the phone object, type and number identify the two phone-related properties.
The phone property is a nested object whose own keys organize details about the phone.
Bracket-Based Recognition
The enclosing brackets provide the quickest first clue. Curly braces mean that you should look for an object organized as key-value pairs. Square brackets mean that you should look for an array organized as an ordered list.
Mistakes in JSON Reading
Treating every JSON structure as an object
Square brackets identify an array, which represents an ordered list rather than an object of key-value pairs.
Fix:
Check the enclosing brackets before interpreting the contents.Assuming every value is a simple string
A JSON value can be an object or an array as well as a string, number, boolean, or null.
Fix:
Inspect the value's own structure. If it opens into another object or array, continue reading at that nested level.Ignoring the order of array members
An array is defined as an ordered list.
Fix:
Preserve the position of each array value when interpreting the collection.Using unquoted object keys
JSON object keys must be strings written in double quotes.
Fix:
Recognize object keys as quoted strings.
Reading Practice
What do you think happens?
A response begins with curly braces. Inside it, one property has a value represented with square brackets. What structure is the outer response, and what structure is that property value?
Reveal answer
Answer: Outer object and inner array
Curly braces identify the outer object. Square brackets identify the nested array. This is an example of an object containing an array.
Describe the structure of this generated data model in words: an outer object represents a customer, one key identifies the customer's name, and another key contains an array of contact methods. Identify the outer structure, the type of each named property, and the nested structure.
Hints
- Start with the outermost container.
- A named property belongs to an object.
- The phrase array of contact methods identifies an ordered collection.
When interpreting an API response, read from the outside inward. Mark each container as object or array, connect each object key to its value, and continue into any nested object or array before deciding what the complete data means.
Key Takeaways
- JSON organizes data with two main structures: objects and arrays.
- Objects use key-value pairs to describe named properties, and their keys must be strings in double quotes.
- Arrays represent ordered lists and use square brackets.
- Objects and arrays can be nested inside one another to create hierarchical data.
- To read a JSON response, identify the outer container first and then follow nested values inward.