What are API Parameters?
API parameters are the variable parts of a resource. They determine the type of action you want to take on the resource. Each parameter has a name, value type ad optional description. Whenever you want to build a REST API, you have to decide which parameters should be present in the API endpoint. In simple terms, API parameters are options that can be passed with the endpoint to influence the response. Read through to learn more about the various types of API parameters and how they are used when making a request.
Types of REST API Parameters
There are four different parts of parameters which are often documented in separate groups on the same page. They include:
- Header parameters – These parameters are featured in the request header and are usually related to authorization.
- Query parameters – These are separated from the hierarchy parameters by a question mark
- Request body parameters – they are included in the request body and are used to send and receive data via the REST API.
- Template/Path parameters – Set off within curly braces, path parameters are placed within the path of an endpoint just before the query string, and they provide developers with an effective way to parameterize resources.
- Matrix parameters – They come in between the resource path and Query parameters and are separated from the hierarchy parameters by a semicolon.
- Plain Parameters – These are parameters which are defined in a request and are easily accessible in ReadyAPI but are omitted when the request is submitted.
Query Parameters
Query parameters are the most common parameter type. It appears at the end of the URL after the question mark (?). The question mark, the parameter, and its real value make what is referred to as the query string. Query parameters come with two distinguishing features from the hierarchy parameters:
- They are optional
- They are non-unique, in the sense that they can be used to specify any one parameter multiple times.
However, it is crucial to note that the order of the query string doesn’t matter as long the variables are correct.
For example, in an airline booking, a customer may wish to add options such as wheelchair access and vegetarian meal.
The URL resource will look like this:
https://airline.server.test/ticketing_api/{flight_id}/{passenger_id}?option=wheelchair&option=vegeterian
or
https://airline.server.test/ticketing_api/{flight_id}/{passenger_id}?option=vegeterian&option=wheelchair
Template parameters
Also known as Path parameters, these parameters are added in the path of an endpoint just before the query string. They are set within curly braces are used to add placeholders that are populated with values for a specified course of action. It is critical to indicate default values, the allowed values, and other details when documenting path parameters. And since path parameters form part of the endpoint, they are not optional.
For example: service/myresource/user/{user}/bicycles/{bicycleId}
In this example, the endpoint, {user} and {bicycleId} are the path parameters. Besides, some developers have started color coding the path parameters to make them more identifiable.
Matrix Parameters
Matrix parameters appear in between the resource path and Query parameters and are separated from the resource path using a semicolon. They are alternatives to query parameters since they offer more flexibility, and they can accept parameters not only at the end but anywhere in the path. Unlike query parameters which apply to the entire request, matrix parameters apply to a specific path element. This comes in handy when making a complex REST-style query to multiple levels of resources and -sub-resources. Additionally, matrix parameters can have more than one value.
Example:
https://example.com/res/categories:name=foo/objects:name=green/?page=1
Plain parameters
These are parameters which are defined in a request and are accessible in ReadyAPI but are not transferred when the request is sent. These parameters appear in the request editor but are not included in the simulated applications. As a developer, you can change some parameter type to plain to ensure that it is excluded from the request simulations.
