An Application Programming Interface (API) is a way for two servers to talk to each other and exchange data. Each API is implemented slightly differently so it’s important to read the documentation. The parameters and the way the parameters are transmitted can be different in each implementation.
API parameters can be split into four different groups:
- Path Parameters,
- Query Parameters,
- Header Parameters, and
- the Request Body.
It’s really important to be consistent when creating an API. There’s a lot of great practices outlined in the article What are REST API’s constraints? and the article 5 Tips for Designing RESTful API URI.
Path Parameters
Path parameters are part of the URL. A placeholder is placed in the URL to denote a path parameter. Usually they’re denoted by a semicolon the name and then a slash (if applicable) or a set of curly braces. The placeholder is then later filled during an API call. Path parameters are not optional.
Here’s an example:
“:BookId” is a Path Parameter. During an HTTP request we would replace “:BookId” with an id to get a single book resource.
Query Parameters
Query Parameters are added to the end of a URL after a question mark. The question mark is followed by a parameter name, and the value.
In the example above, publishing_year is a parameter and 2022 is the value.
Parameters should be optional and the ordering of parameters shouldn’t matter. Multiple parameters and values can be used in a URL.
A query string should normally be used for pagination or for searching. I like to optionally add a sort parameter.
Header Parameters
Parameters can be passed in the request header. Usually header parameters are used for passing sensitive data that shouldn’t be cached like a Bearer Token or an API key.
Sometimes, a Header Parameter can be used for requesting a specific version or the API or a specific type of response. You can read more about that in the article Versioning in REST APIs.
Request Body
Request Body Parameters are commonly used in POST, PUT, or PATCH requests. Usually the request body is in the form of a JSON object or in XML.
If it’s JSON the the object contains key-value pairs. The key value pairs in a JSON object will often look something like this:
Then the JSON object is added to the request body.
Wrapping It Up
In this article, we looked at the different ways variables can be transmitted to the server. Values can be transmitted as Path Parameters, Query Parameters, Header Parameters, and through the Request Body.
Also published on Medium.
