API Response

Are you trying to integrate an API into your app but cannot retrieve the data you're requesting or successfully post your content? The server is likely telling you how to fix the issue, but if you're not familiar with how API responses work, you won't know what a status code is or where to find them.

What Is an API Response? 

An Application Programming Interface (API) response is what an API provider (the server) returns to you (the client) after handling your API request. The request tells the server what you want to do, and the response lets you know if it was successful and returns any data you might have requested.

If you're building a travel app and want machine translation capabilities without coding it yourself, you can integrate one of the freely-available translation APIs.

When a user translates something from English to Spanish, your app will send a request with the English text to the server. Unless there is an error, the server will respond with a success code and the Spanish translation, allowing you to display it for the user in your app.

But how does this work?

How Do API Responses Work? 

A successful API response works by fulfilling the client's request. An unsuccessful response acknowledges the request but returns information indicating an issue on the client's side or server's side or that a resource has been moved.

API responses will differ depending on a number of factors, like:

• The nature of the request
• The API protocol
• Whether the provider requires an API token or key
• Whether there is a rate limit and if the client has gone over it

Representational State Transfer (REST) APIs are the most common type, and they run on HTTP/HTTPS. REST API response structure is composed of:

• Status line: Contains the HTTP version and HTTP codes that let a user know in detail whether their request was successful.
• Headers: Key-value pairs that contain metadata information about responses, like content type and length, cookies for the client to store, and rate limit details. 
• Response body: This section varies depending on the nature of the request and the response status. It may contain items like the requested data, an acknowledgment that a resource was created or updated, an error message, and images. Some common formats for text returned in the response body are JSON, XML, HTML, YAML, and plain text.

When your app sends the request to translate a user's English "Hello" into Spanish via the API, the server receives it and begins processing it. Depending on the provider's specifications, it might check your API key or token before executing the translation.

If the request was successfully fulfilled, the response might look like:

HTTP/1.1 200 OK

Content-Type: application/json

{
   "translation": "Hola"
}

The status line contains the HTTP version, the response code, and an OK, showing the request was successful. The header indicates that the response body is formatted in JavaScript Object Notation (JSON). The response body contains the translation.

If the request failed because of a user error in the request's URL, the response might look like:

HTTP/1.1 404 Not Found

Content-Type: application/json

{
   "error": 404,
   "message": "Resource not found."
}

The response will display a different code and message depending on the error. Unless there is a timeout caused by network or server issues, the server will send back an acknowledgment to let the client know something went wrong.

API Response Time

Whether you're using a chat or video API, an important measurement to keep in mind is API response time. This is the total time it takes for a server to receive the request, process it, and send the response back to the client.

There are three relevant metrics for measuring response time:

• Average response time: The average time the server takes to respond.
• Peak response time: The slowest measured response time from the server.
• Error rate: A percentage representing the number of times an error code has been returned instead of a successful response.

These metrics matter because APIs with slow average response time, high peak response times, or high error rates can drive users away from the apps that integrate them — or developers away from the API.

Types of API Responses 

Responses will look different depending on the API protocol type used. Here are the structures of responses in four common API protocols:

• RPC response: Can use different transfer protocols like HTTP/HTTPS, UDP, and TCP. When using HTTP, the structure will look similar to a REST API response with a status line, headers, and a response message body. Common formats for the message body are JSON and Protocol Buffers (when using the gRPC framework). TCP and UDP-based responses lack status lines and headers.
• SOAP response: Similar to RPC responses, but the response message body is confined to a SOAP-specific XML envelope structure.
• GraphQL response: Similar to REST responses, but the response message body is always JSON and only contains "data" and "error" fields.
• WebSocket response: The WebSocket protocol allows bi-directional communication between client and server. There is an initial HTTP/HTTPS response, which is formatted with a status line and headers and confirms the switch from HTTP/HTTPS to WebSockets. Afterwards, messages can be sent freely between client and server in JSON, plain text, or binary formats.

How Can You Optimize API Response Time on the Client Side?

Much of the response time optimization work will need to be done by the API provider, but there are a few things you can do on the client side to improve performance, like:

• Caching: Cache previously retrieved data that is static or won't change often. How and what to cache will depend on the API type and provider's specifications. If a user of your travel app translates the same message multiple times, the app could retrieve that message from its cache instead of sending a request to the server.
• Pagination: Convert retrieved data into smaller segments to improve load times instead of waiting for the server to return all the data. Each segment will load quickly when needed, like a scrollable feed of your company's posts on a social media platform. There are multiple ways to paginate results, but a common way is using query parameters to limit or filter results. Reference the API's documentation for the query parameters to use for this purpose.
• Limiting payload size: Limit your headers and parameters in your requests to only what is needed. When only a specific segment is needed, unnecessary information or requests for large amounts of data will lead to slower response times.

Frequently Asked Questions