What are the components of an API?

The Postman Team

April 14, 2023

APIs are sets of code-based instructions that enable software components to communicate and transfer data, and they are the building blocks of all modern applications. But what are the building blocks of APIs themselves? In this article, we’ll review the different components of a REST API by following a request from end to end.

API client

API requests can be triggered in many different ways. For instance, a user might initiate an API request by entering a search term, clicking a button, or scrolling through a list on a web or mobile application. API requests may also be issued in response to external events, such as a notification from another application or service. No matter how the API request is triggered, an API client will be responsible for assembling and directing it to the API server.

It’s important to note that the phrase “API client” can mean different things depending on context. First, it can refer to a development tool that abstracts away some of the complexity of manually sending API requests, which makes it easier to explore, test, and debug APIs. It can also refer to a service that uses language-specific libraries and SDKs to initiate API requests in the context of a larger application. Both types of API clients are responsible for handling the data returned by the API and presenting it to the user, but the latter type of client may also use the returned data in the application’s logical flow.

API request

We mentioned that an API client is responsible for sending API requests in response to user actions or external events, but what, exactly, is an API request? An API request will look and behave differently depending on the type of API. That being said, an API request to a REST API is comprised of the following components:

• Endpoint: Every API request is directed to an API endpoint, which is a dedicated URL that provides access to a specific resource. For instance, the /products endpoint in an e-commerce app would include the logic for processing all requests that are related to products. The request must therefore designate an endpoint so the API server knows how to proceed. We’ll discuss the API server in more detail soon.
• Method: Every API request must include a method, which defines the operation that the client would like to perform on the specified resource. REST APIs are accessible through standard HTTP methods, such as GET, POST, PUT, PATCH, and DELETE, which facilitate common actions like retrieving, creating, updating, or deleting data. A GET request to the /products endpoint would tell the API server to return every product in the database.
• Parameters: Parameters are the variables that are passed to an API endpoint to provide specific instructions for the API to process. These parameters can be included in the API request as part of the URL, in the query string, or in the request body. For example, the /products endpoint of an e-commerce API might accept a “color” parameter, which it would use to access and return products of a specific color.
• Request headers: API request headers are key-value pairs that provide additional information about the request. For instance, the Content-Type header specifies the format of data in the request body, while the Authorization header provides authentication credentials, such as an API key or OAuth token, to authenticate the requester.
• Request body: The request body includes the actual data that is necessary to create, update, or delete a resource. For instance, if an administrator of an e-commerce store needs to create a new product, the request body might include the product’s name, brand, and price. The API specification will dictate the required data format for the request, such as JSON or XML.

API server

Once the API client assembles the request, it sends it to the appropriate endpoint on the API server for processing. The API server is responsible for handling authentication, validating input data, retrieving or manipulating data from a database, and returning the appropriate response to the client.

It’s important to note that while the database itself is not an API component, the API cannot function without it. Whereas the API server retrieves and manipulates application data based on a request, the database stores and organizes this data in a way that facilitates efficient retrieval and manipulation. The API server therefore acts as an intermediary between the API client and the database.

API response

We mentioned above that the API server is responsible for sending a response to the client after it has processed the request. The content of API responses can vary widely depending on the type of request and the design of the API, but they typically include the following components:

• Status code: API status codes are HTTP status codes that are returned by an API to indicate the status of a client’s request. These codes are used to provide information to the client about the outcome of the request and to help the client understand how to proceed. Some of the most common status codes include 200 OK, which indicates that the server successfully returned the requested data, 201 Created, which indicates the server successfully created a new resource, and 404 Not Found, which indicates that the server could not find the requested resource.
• Response headers: HTTP response headers are very similar to request headers, except they are used to provide additional information about the server’s response. For instance, the Cache-Control header provides instructions for how long the data can be stored in a cache, while the Set-Cookie header sets a cookie in the browser, which can be used for session management or authentication.
• Body: The response body contains the data or content that is returned by the API server in response to the client’s request. Response bodies vary widely, but they typically include structured data objects that represent the requested resources, metadata, and—if the request failed—error messages about what went wrong. For instance, a successful GET request for a specific product might include a JSON representation of that product, as well as a timestamp and the source of the data.

While REST is the most common API architecture, other types of APIs, such as GraphQL and gRPC, will have different components. Nevertheless, this list includes the core components that are involved in executing requests to every RESTful API.