REST API Parameters Types

Profile picture for user devraj

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.

REST APIs have following types of parameters:

  1. Header Parameters
  2. Cookie Parameters
  3. Path Parameters
  4. Query Parameters
  5. Body Parameters
  6. Matrix Parameters
  7. Form Parameters
  8. Plain Parameters

Header parameters are included in the request header. Usually, the header just includes authorization parameters that are common across all endpoints; as a result, the header parameters aren’t usually documented with each endpoint.  Header parameters named Accept, Content-Type and Authorization are not allowed.

GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

Operations can also pass parameters in the Cookie header, as Cookie: name=value. Multiple cookie parameters are sent in the same header, separated by a semicolon and space.

GET /api/users
Host: example.com
Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ

3. Path/Template parameters

Parameters within the path of the endpoint, before the query string (?). These are usually set off within curly braces.

/service/user/{userid}/orders

4. Query string parameters

Parameters in the query string of the endpoint, after the ?. The question mark followed by the parameters and their values is referred to as the “query string.” In the query string, each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter.

/service/{beachId}?days=3&units=metric&time=1400

5. Request body parameters

Parameters included in the request body. Usually submitted as JSON. Frequently, with POST requests (where you’re creating something), you submit a JSON object in the request body. This is known as a request body parameter, and the format is usually JSON. This JSON object may be a lengthy list of key-value pairs with multiple levels of nesting.

{
"days": 2,
"units": "imperial",
"time": 1433524597
}

6. Matrix parameters

They come in between the resource path and Query parameters and are separated from the hierarchy parameters by 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.

http://example.com/res/categories;name=foo/objects;name=green/?page=1

7. Form Parameter

Form parameters are used to describe the payload of requests with Content-Type of:

  • application/x-www-form-urlencoded (used to POST primitive values and arrays of primitive values).
  • multipart/form-data (used to upload files or a combination of files and primitive data
<form action="http://example.com/survey" method="post">
  <input type="text"   name="name" />
  <input type="number" name="fav_number" />
  <input type="submit"/>
 </form>

This form POSTs data to the form’s endpoint:

POST /survey HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 29
name=Amy+Smith&fav_number=321

8. 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.

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.