1. The basic anatomy of an API request
Fetching data from an API is straightforward; now, let's learn how we can use the requests package to give more detailed instructions to an API.
2. What are URLs?
URLs are a fundamental concept in Web APIs. A URL is a structured address pointing to a specific resource. Via a URL, we can specify what resource we want to interact with.
For this example we'll compare a REST API to an office building; each office unit is a unique resource. The URL is the address of a single unit in the building. It contains all the information needed to navigate to that specific unit.
3. Dissecting the URL
Let's break URLs down into its five main components.
First is the protocol. This determines the transportation to use when navigating to the destination, walking or driving, for example.
The second component is the domain, it is like the street address of the office building. It uniquely identifies the location of the API server on the internet.
Third is the port, the gateway or entrance into the office building. When traveling by car, we enter through the garage. Common default ports are 80 and 443.
The path component determines the specific office unit in the building. With APIs, each resource has a unique location on the server, defined by its path.
The last component is the query, which contains additional instructions. It specifies instructions like "take the elevator" for example.
By constructing a URL with a path and parameters, we can control where to send our API requests to.
4. Adding query parameters with requests
Adding a query parameter using the requests package is very easy. We might want to just append the query parameter to the URL string, which works fine, but there is a better way.
Each HTTP method from the requests package, such as get, accepts an additional argument called `params` which accepts a dictionary with key/value pairs, one for each query parameter. See how much easier that code is?
5. HTTP Verbs
Let's send a package to the DataCamp office! Using the URL, we have constructed the destination of our package: the mailbox of unit 243 in the Empire State building.
But how do we now define what to do with the package when we arrive at our destination? This is where HTTP verbs come in. Every request uses one of 9 HTTP verbs, let's learn the four most important ones.
GET is used to read a resource. It's like checking the contents of the mailbox without taking anything out.
POST is creating a resource, like dropping a new package in the mailbox.
PUT updates a resource, like replacing a package that was already in the mailbox.
And DELETE removes all packages from the mailbox, leaving it empty.
6. Sending data via POST and PUT
With the requests package, we have easy access to all HTTP verbs as functions; we already saw the `requests.get()` function.
For POST and PUT requests, we need to add data to create or update our resources. Similar to how we can pass a `params` argument to set query parameters, we can also pass a `data` argument to specify the data we want to send along with the request.
Making a DELETE request is even simpler. Just use the delete instead of the get function.
7. Let's practice!
Great! Now let's practice.