API Request

APIs are essential for using and developing software. To use an API, the client needs to send a request to the server. Read on to learn what API requests are, how they work, and more. What Is an API request? 

An Application Programming Interface (API) request, also known as an API call, is a key step in activating an API. It's how we (the client) let the API (the server) know what we want to do with it.

If you're building a travel app and want to show your user a destination's weather information, you don't need to build weather forecasting functionality from scratch. You can integrate one of the freely available weather APIs.

When the user looks up Hanoi, your app will send an API call to the API provider, asking for the city's forecast data. If you coded everything right, the request will be successful, and your app will display the relevant content of the API response to the user.

How Does an API Request Work? 

Whether you're using a chat or video API, an API request works by telling the API how we want to use it via the information our request contains. How we structure and send this information depends on the API protocol type.

We will look at Representational State Transfer (REST) requests because REST APIs are the most commonly used type and easiest to learn. REST uses HTTP/HTTPS protocols, and their ways of making requests are very similar.

REST API call structure consists of:

• Endpoint URL: The address of the API.
• Status line: Contains the HTTP method, path and query parameters, and HTTP version used.
• HTTP method: What you want to do with the resource with methods like GET, POST, PUT, and DELETE.
• Parameters: Path parameters identify the path of the resource you're requesting. Query parameters specify things like the exact resource you want, how responses will be sorted, and the languages you or your users speak.
• Headers: There are many different headers, but some of the most common ones relate to formatting for the data sent or requested, caching, authorization, and authentication. 
• Request body: Where you store the data you're sending the server if you're using methods like POST and PUT.

If a user checks the weather forecast for Hanoi tomorrow using your app, it will send the request to the endpoint URL using parameters to specify the requested information. The full URL might look something like api.fakeweathercompany.com/forecasts?city=hanoi&date=tomorrow.

The endpoint URL is api.fakeweathercompany.com. The path parameter is /forecasts, and the query parameters are ?city=hanoi&date=tomorrow.

The HTTP method to retrieve the forecast is GET. Depending on your app and the API, the header field might use Accept to request the weather data in JSON.  If the API requires a key, it might also be stored in the header. In its simplest form, the request would look like:

GET /forecast?city=hanoi&date=tomorrow HTTP/1.1

Host: api.fakeweathercompany.com

Accept: application/json

The request will look much different when coding your app, but the basic structure will be the same. If everything works right, you should receive a response with a 200 status code, and the app will display the forecast contents for your user.

Types of API Requests

There are some differences in how requests are structured depending on the protocol. You already know what a REST call looks like, so let's look at the structure other protocols use:

• RPC request: Usually uses JSON or XML as determined by how the provider designed the API. RPC can use communication protocols like HTTP/HTTPS, TCP, UDP, and more. Structurally, an RPC call contains a predefined method specific to the API, parameters to go along with the method, and any necessary metadata related to the call. RPC calls only use the GET and (most often) POST HTTP methods.
• SOAP request: Sends XML files over different protocols, including HTTP/HTTPS, TCP, and UDP. Structured with an envelope to mark the beginning and end of the request, optional headers similar to REST, and a body with the request data you might send to the server.
• GraphQL request: Uses JSON and (most often) HTTP/HTTPS with the POST method. The structure resembles a REST request, but GraphQL only uses the POST method, with the data inside the JSON being either a query or a mutation. Queries retrieve data with more specificity than allowed in other protocols, and mutations indicate the equivalent of write, update, and delete operations. 
• WebSocket request: Sends an initial HTTP request to the client to establish a continuous connection for real-time communication between client and server. This request is called a handshake, and it contains an endpoint URL with path parameters, the GET HTTP method, and headers for establishing the connection. WebSocket APIs can send and receive JSON, plain text, binary, and more.

How to Send Your First API Request 

Sending your first request is easier than you think. You can do it by following these steps:

1. Find a simple public API from a trusted list that interests you.
2. Pick an easy-to-use API testing tool like Postman, RapidAPI, or Insomnia.
3. Enter the full URL into the bar, including the endpoint URL, the path parameter, and any desired query parameters.
4. Pick the GET method and send the request.

If you formatted the URL correctly and there are no issues on the server's side, you should receive a response with the information you asked for. In actual use cases, you need to integrate the API into your app or site to use it. This will look different depending on the language(s) and framework(s) you use.

API Request Best Practices

In addition to following general API best practices, you should:

Read and refer back to the API developer's documentation often, and make sure you read the docs to fully understand how you should format your calls. They should tell you everything you need to know about the endpoint URL, path parameters, possible query parameters, what's required and what's optional for headers and body messages, how to handle errors, and more.

There are usually examples of requests and responses for reference, too.

You should also test requests before allowing users to make them. Make sure all of your app's possible requests can't expose your, or the provider's, sensitive information. For example, check that data retrieved from a REST API with GET properly displays in the app.

For better security, hide your API tokens and keys in the headers of REST APIs instead of the body or URL, where threat actors are more likely to use them. You can test requests using tools like SoapUI, Katalon Studio, Paw, Postman, or Insomnia.

Also, be aware of and respect rate limits. The most common response after going over a rate limit is a 429 response code, indicating that too many requests were sent. Depending on the API, clients may get hit with penalties or suspensions for going over the limit too often or may receive a high usage bill.

And, finally, be sure to account for rate limits when integrating. When possible, batch requests, cache responses, monitor and log API usage, and contact the provider if a higher rate limit is needed.

Frequently Asked Questions