Published on August 10th, 2024, Updated on August 14th, 2024
Check-out our JSON Tool & other free AppsWhen designing a new REST API, your API can receive inputs via:
Can you simply choose any one of these four methods for receiving input from client applications?
Or is there a rationale behind preferring one method over another when passing input to a REST API?
In this article, we will explore the best practices for selecting the appropriate input method.
Let's assume that we are building a REST API designed to return a list of movies. Additionally, let's assume that the API requires the following inputs before it can return the list of movies:
Let's also assume that this REST API is secured, meaning that any application calling this API must also provide a valid username and password; otherwise, the API would not return the list of movies to the calling application.
So, essentially, this REST API need 4 inputs:
So, how should a client application pass all this information to this REST API?
Which one of the four ways should the API designer pick when building this REST API?
The simple answer is that the API designer can pick any of the four ways for receiving inputs from calling applications.
Whether you decide to use HTTP Headers, or Path Variables or Query Parameters or HTTP Request Body, each method serves the same purpose: providing the necessary inputs to the API so that it can produce the response. The API designer can also choose a combination of way to receive inputs, for example, some inputs can be received via HTTP headers, other inputs via path variables and query parameters or some other combination.
When deciding how to receive inputs, there are some common practices that API developers/designers follow. Below we will discuss one way of passing the 4 inputs to API that returns the list of movies.
Let's first discuss the common way of passing username and password to the API. It is common practice to pass username and password as Header or Headers to the REST API. There is actually a dedicated header called Authorization and the purpose of that field is to pass authorization data to REST APIs. Alternatively, we can define custom headers also, one custom header for passing the username to the API and another custom header to pass the password. HTTP Headers help us keep the auxillary data (or metadata) separate from the actual data being exchanged between the API and the application calling the API. If we think about it then the calling application is really asking the REST API to send it the list of action movies (genre) from the year 2022 (movie year) and if the API wants to know if the calling application is really authorized to receive the list of movies then the API can look at the header section of the HTTP request and obtain the username, password or the authorization token. Other commonly used HTTP headers are Content-Type and Content-Length headers.
Now let's talk about how the calling application can pass the movie year and genre information to the API. It is not a common practice to pass data to the API via HTTP Headers, we can do that but we won't because it is not the norm. We have three options available to us:
Pass the movie year and genre via path variables, something like this:
https://www.apioncloud.com/movies/year/2022/genre/action
where, 2022 is the first path variable and action is the second path variable.
Why are path variables called variables? Because their value can vary. I can change the year value to 2024 and genre value to comedy, like below:
https://www.apioncloud.com/movies/year/2024/genre/comedy
Pass the movie year and genre as query parameters, somethin like below:
https://www.apioncloud.com/movies?year=2022&genre=action
where, year is the query parameter key and 2022 is the query parameter value. The second query parameter key is genre and its value is action
And just like path variables, the value of query paramters can change, for example, the call below is also valid:
https://www.apioncloud.com/movies?year=2023&genre=adventure
NOTE: We cannot change the name of the keys in Query Parameters. Keys are the words year and genre
The last option to send inputs to the API is via HTTP Request Body. When choosing to use HTTP Request Body for sending inputs then we need to stick to the format that is accepted by the REST API. For example, the designer of the API may require the inputs must be provided in JSON or XML, plain-text or some other format. The most common format is JSON, something like this:
{
" year": 2022,
" genre ": "action"
}
It is the same information, but just sent in a different way to the API.
It is important to mention that it is not a common design practice to ask for inputs via request body when the API handles HTTP GET requests. However, if the REST API accepts POST or PUT requests then asking that the inputs be provided to the API via request body is perfectly acceptable.
Using HTTP request body for sending inputs to the API is ideal when the input involves complex data, such as, nested data, data that has parent-child relationships etc.
Another question that arises here is whether the REST that we are building should respond HTTP GET, POST, or PUT requests?
The answer is that we can choose any of these three methods since we are designing and developing the API. However, because this API is intended to retrieve a list of movies, it's most appropriate for the API endpoint to respond to HTTP GET requests only.
Remember, it’s not a common practice to request inputs via the HTTP request body when the API responds to HTTP GET requests. This means we cannot pass the year and genre through the request body. Therefore, we’re left with two options: providing inputs through path variables or using query parameters.
Using path variables to send input data to the API are considered clean and user-friendly and also REST ful approach. The term REST in REST API comes from RESTful, which is an architectural style. APIs that adhere to RESTful architecture are called REST APIs. You can read more about clean URLs here.
However, this doesn't mean that no one uses query paramters to pass input data to REST APIs. Infact, using query parameters is very common practice. The rationale behind using query parameters is that they are ideal for providing queries or search criteria. Think of the REST API as a service that has several hundred thousand movies in its database, but the client application is only interested in a subset—specifically, action movies from the year 2022. So, using query parameters to pass inputs to the REST API also make sense. The client application is asking the API to return only those movies that match the provided inputs or search criteria.
It is also worth mentioning that query parameters has other very common uses, such as:
The API developer can choose one approach over another based on personal preference or specific reasoning.
For example, if the movies are stored in a database table then the API developer may conclude that using query parameters is ideal because the developer has to search or query the database to obtain the needed list of movies and send that list to the calling application.
On the other hand, if the movies are stored as files on a storage device, one file containing movies from a particular year and genre, then the same developer may choose to use path variables.
We hope you found this discussion insightful!
Watch the video version of this discussion on YouTube here:
Be sure to check out our free online tools, and keep coming back— we're continuously working on adding new tools to supercharge your productivity!