Page Comparison

Header parameters

Header parameters are included in the request header. Usually, the header just includes authorization parameters that are common across all endpoints.

Path parameters

Path parameters are part of the endpoint itself and are not optional. For example, in the following endpoint, {user} and {bicycleId} are required path parameters:

/service/myresource/user/{user}/bicycles/{bicycleId}

Query string parameters

Query string parameters appear after a question mark (?) in the endpoint. 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.

For example:

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

and

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

would return the same result.

Request bodies

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, and the format is usually JSON. This JSON object may be a lengthy list of key-value pairs with multiple levels of nesting.

For example, the endpoint may be something simple, such as /surfreport/{beachId}. But in the body of the request, you might include a JSON object with many key-value pairs, like this:

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

Note: In OpenAPI v2.0, request bodies were classified as a type of parameter, but in v3.0, they are not considered a parameter but rather a path property.