1. Working with structured data
So far, we have only used simple requests, such as getting song lyrics represented as a string of text. In reality, we often need to exchange more complex data structures. Let's learn how to handle these kinds of API requests.
2. Complex data structures
The lyric API returns the entire lyric as plain, unstructured text. Complex data types, like music albums, require more structure to transmit effectively. That's because albums have multiple properties, such as an ID, title, artist, or list of tracks.
3. Complex data structures: JSON
Luckily, we have a few handy data formats to make working with structured data easier. In this examples we are using JSON, which stands for Javascript Object notation. It is the most common and a very lightweight format used by web APIs. JSON is natively supported by many programming languages and easily readable by both humans and machines.
JSON is one of the many types we call content-types, mime-types, or media-types. These terms are used interchangably, but in this course we will use the term "content type".
Other formats we might encounter are XML, CSV, and YAML.
4. From Python to JSON and back
In order to use a Python object with a Web API, we first need to convert it to a JSON string so we can safely transmit it with the request or response. Transforming a Python object to JSON is called encoding. Decoding is the reverse, turning a JSON string back into a Python object.
In Python, the built-in `json` package can encode and decode JSON. `json.dumps()` turns a Python object into a JSON string, while `json.loads()` converts a JSON string back into a Python object.
5. Requesting JSON data
Let's see how the requests Python package can help us work with APIs using JSON as data format.
Using the get function, we request a lyric from the API. Without adding additional headers, the server will respond in plain text.
When we add an accept header with the value `application/json`, the server will respond with JSON text. We can inspect the JSON text by just printing the response.text. Using the json() function on the response object, we can now decode the JSON text into a Python object and easily print the artist attribute.
6. Sending JSON data
We've now learned how to receive JSON data, but what about sending JSON data? The requests package can also help here. When using the `json` function argument to send the playlist object, requests will automatically add the necessary content-type headers and do all of the encoding for us.
Let's inspect the request object after sending the playlist object to the playlists API. Notice that the content-type header is set to `application/json` automatically. We didn't need to add any headers or encode objects to JSON strings.
7. Let's practice!
The requests package makes working with JSON really easy. Now that we know how to send and retrieve JSON data, let's put what we learned to the test.