Working with APIs and JSON Responses
JSON has two main structures: objects, which hold key-value pairs, and arrays, which hold ordered lists.
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.
- 1Find the outer structure
The outer structure is an object because it is represented with curly braces.
- 2List the keys
The object has the keys name, phone, and email.
- 3Classify the values
The value for name is a simple string. The values for phone and email are themselves objects.
- 4Read 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 |
The two primary JSON structures serve different organizational purposes.
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.
- 1Start at the contact object
The outer object represents the contact and contains named properties.
- 2Follow the phone key
The phone key points to another object rather than to a simple value.
- 3Read 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
Common mistake Treating every JSON structure as an object
What it looks likeA value enclosed in square brackets is read as if it were a set of named properties.
Why it failsSquare brackets identify an array, which represents an ordered list rather than an object of key-value pairs.
Do this insteadCheck the enclosing brackets before interpreting the contents.
Common mistake Assuming every value is a simple string
What it looks likeThe phone value in a contact object is treated as one plain text value.
Why it failsA JSON value can be an object or an array as well as a string, number, boolean, or null.
Do this insteadInspect the value's own structure. If it opens into another object or array, continue reading at that nested level.
Common mistake Ignoring the order of array members
What it looks likeThe members of an array are treated as an unordered group.
Why it failsAn array is defined as an ordered list.
Do this insteadPreserve the position of each array value when interpreting the collection.
Common mistake Using unquoted object keys
What it looks likeAn object key is treated as a bare label rather than a string.
Why it failsJSON object keys must be strings written in double quotes.
Do this insteadRecognize 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
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.