The structure of an API request
Dec 16, 2021
Each of these pieces plays an important part in sending and receiving data with an API, and so I will walk you through each one in turn. Some parts of an API request are optional depending on what kind of request it is and what you are trying to do with it, but there are two pieces that are required for every API request. Every API request needs an endpoint and an action.
API endpoints
Every web-based API request must specify an endpoint. In the Postman requests tab, you are prompted to enter the request URL. Postman is asking you to put in a URL
because an API endpoint is just a URL. We use the term URL so much that we can sometimes forget what it stands for. URL is an acronym for Uniform Resource
Locator. The endpoint of an API call specifies the resource, or the "R" of the URL. In other words, an API endpoint is the uniform locator for a particular resource that you
want to interact with on the server. URLs help you to locate resources on a server, and so they are used as the endpoints in an API call.
Fill in this field in the requests tab by typing in the following URL: https://api.github.com/users/djwester/repos. This endpoint will give you information about my
repositories on GitHub. If you have a GitHub account of your own, you can put in your username in the part of the URL where it says djwester and get back data for your
own repositories.
You will often see an API endpoint specified without the base part of this API. So, for example, if you look at the GitHub API documentation, it will report the endpoint for
this as /users/:username/repos. All the GitHub API calls start with the same base URL (in other words, https://api.github.com), and so this part of the endpoint is often left
out when talking about an endpoint. If you see API endpoints listed that start with a / instead of with http or www, just remember that you need to go and find the base
API URL for the endpoint in order to call it.
API actions
Every API call needs to specify a resource that we are working with. This is the endpoint, but there is a second thing that every API call needs. An API needs to do
something with the specified resource. We specify what we want an API to do with API actions. These actions are sometimes called verbs, and they tell the API call what
we expect it to do with the resource that we have given it. For some resources, only certain actions are valid, while for others there can be multiple different valid API
actions.
In Postman, you can select the desired action using the drop-down menu beside the textbox where you entered the URL. By default, Postman sets the action to GET, but if
you click on the dropdown, you can see that there are many other actions available for API calls. Some of these actions are specialized for particular applications, and so
you won't run into them very often. In this book, I will only use GET, POST, PUT, and DELETE. Many APIs also use PATCH, OPTIONS, and HEAD, but using these is
very similar to using the four that I will use, and so you will be able to easily pick up on how to use them if you run into them. The rest of the actions in this list are not
often used and you will probably not encounter them much in the applications that you test and create.
The four actions (GET, POST, PUT, and DELETE) are sometimes summarized with the acronym CRUD. This stands for Create, Read, Update, and Delete. In an API, the
POST action is used to create new objects, the GET action is used to read information about objects, the PUT action is used to modify existing objects, and (surprise,
surprise) the DELETE action is used to delete objects. In practice, having an API that supports all aspects of CRUD gives you the flexibility to do almost anything you
might need to, which is why these four actions are the most common ones you will see.
API actions and endpoints are required for web APIs, but there are several other important pieces to API requests that we will consider.
API parameters
API parameters are used to create structure and order in an API. They organize similar things together. For example, in the API call we are looking at, we are getting the
repositories for a particular user in GitHub. There are many users in GitHub, and we can use the exact same API endpoint to get the repository list for any of them with
the change of username in the endpoint. That part of the endpoint where it accepts different usernames is a parameter.
Request parameters
The username parameter in the GitHub repositories API endpoint is known as a request parameter. You can think of a request parameter as a replace string in the API
endpoint. They are very common in web APIs. You will see them represented in different ways in the documentation of different APIs. For example, the GitHub
documentation uses a colon in front of the request parameter to indicate that it is a request parameter and not just another part of the endpoint. You will see endpoints
specified like this in the GitHub documentation: /users/:username/repos.
In other APIs you will see request parameters enclosed in curly braces instead. In that case, the endpoint would look like /users/{{username}}/repos. Whatever the format
used, the point of request parameters is to get particular information about different objects that are all the same type. We have already seen how you can do that with
this endpoint by replacing my username with your username (or any other GitHub user's name).
Query parameters
There is another kind of parameter that you can have in an API endpoint. This kind of parameter is known as a query parameter and it is a little bit trickier to deal with.
A query parameter often acts like a kind of filter or additional action that you can apply to an endpoint. They are represented by a question mark in the API endpoint and
are specified with a key that is the item you are querying for, and a value, which is what you want the query to return.
That's all very abstract, so let's take a look at it with the GitHub request we have open. This endpoint supports a couple of different query parameters. One of them is the
type parameter. In order to add parameters to an API endpoint in Postman, make sure you have the Params tab selected and then put the name of the query parameter
into the Key field and the value into the Value field. In this case, we will use the type parameter, so enter that word into the Key field.
For this endpoint, the type parameter allows us to filter based on whether you are the owner of a repository or just a member. By default, the endpoint will return only
those repositories that you are the owner of, but if I want to see all the repositories that I am a member of, I can put member in the Value field for this. At this point, the
request should look something like this:
Figure 1.1 – Query parameter type in an API call
If I send this request, I get back all the repositories that I am a member of, as opposed to the ones that I own. Parameters are a powerful API paradigm, but there are still
a few more fundamental pieces of the API structure that I haven't talked about yet. The next thing we will look at are API headers.
API headers
Every API request needs to include some headers. Headers include some of the background information that is often not that important to human users, but they help the
server have some information about the client that is sending the request. Sometimes, we will need to modify or add certain headers in order to get an API to do what we want, but often we can just let the tool that we are using send the default headers that it needs to send without worrying about it.
In Postman, you can see what headers will be sent with your request by using the Headers tab. You can also modify the headers and add additional ones here as needed. I
will get into more details on how headers work and how to use them in future chapters, but for now, you don't need to worry about them too much. The point of
mentioning them here is just to make sure you know the terminology. Let's turn our attention instead to the body of an API request.
API body
If you want to create or modify resources with an API, you will need to give the server some information about what kind of properties you want the resource to have. This
kind of information is usually specified in the body of a request.
The request body can take on many forms. If you click on the Body tab in the Postman request, you can see some of the different kinds of data that you can send. You can
send from-data, encoded form data, raw data, binary data, and even GraphQL data. As you can imagine, there are a lot of details that go into sending data in the body of a
request. Most of the time, GET requests do not require you to specify a body. Other types of requests, such as POST and PUT, which do require you to specify a body,
often require some form of authorization since they allow you to modify data.
Once you can authorize requests, there will be a lot more examples of the kinds of things you might want to specify in the body of an API request.
<
