What is an API call?
Greetings, and welcome to the third of a miniseries on the blog covering some fundamental concepts in APIs, or Application Programming Interfaces.
We’re taking a different approach with these posts; instead of providing a long and detailed explanation of APIs and the most important things to know in a single post, we’ll be breaking them down and making each entry short and punchy.
That should help you find the answers you’re looking for quicker, and perhaps even encourage you to read the full post rather than give it a quick skim. Here’s hoping!
This is a quick primer on API calls. We already have posts up on API endpoints and API keys, so make with the clicky if you haven’t read those already. Ready? Let's go!
API calls defined
An API call or API request is the message sent from the client to the service. You make an API call to the endpoint, often using an API key. You can compare the call to mailing a letter, where the endpoint acts as a mailbox or destination address.
How to make an API call
To build a call, you need to supply the following:
The address — the URL of the API endpoint with optional parameters
The action — the request type, such as GET or POST
A header — for adding details, authentication, etc.
Optional data (also called a payload)
Every service that processes API calls constantly listens for requests to process. (For web traffic, these services generally listen to port 80 or 443.) The services retrieve client requests, ensure they include the appropriate security data (e.g., API keys, headers), unpack the parameters and data used, then return a response to the client.
Some examples of API calls
Here’s an example of an API call that you can try on your terminal (this functionality is built-in to macOS and Linux):
curl https://api.github.com/repos/torvalds/linux
This will use the GitHub REST API to return some information about the code of the Linux kernel, which is used on everything from ATMs to space stations. You can make an API call with every programming language.
Let’s look at another example in a more visual way using Postman, a web API platform with a great user interface. It’s a very useful tool to try out public APIs. Our example will build a request using JSON parameters and headers. Then, Postman will request data and display the response we receive.
To use the Contentful API to retrieve all the Content Types in a given Space, we’d use the following endpoint:
https://cdn.contentful.com/spaces/nxk0n1u8oy59/content_types
If you enter that endpoint directly as a GET request in Postman, you will receive the following “401 Unauthorized” status and an error message requesting an access token:
Now, if you added the access token to the request header, either by using the Authorization tab or adding the header manually, you would then receive the following result:
The response header also returns metadata about the endpoint that received the request, including the organization ID and the region from which the request originated.
Although this example is a read-only API, other APIs allow you to push information into the destination system. If you wanted to build a request to create or update data, it usually looks like the following:
Change the request type from
GETtoPOST(or any other http verb).Add the formatted JSON data to the request body. (JSON is one of the most popular data formats.)
Set the request’s Content-Type header to application/json.
Then your data would be sent to the service in the request body.
Wrapping up
Now you know how to make an API call using Contentful or other methods. As a reminder, APIs work everywhere and power every tech we use, not just websites, but your iOS/Android apps too, and probably your toaster. Check out our other posts on API endpoints and API keys. Hopefully you found them useful!
