Step 3: Parameters (API reference tutorial)

Parameters: Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are four types of parameters: header parameters, path parameters, query string parameters, and request body parameters. The different types of parameters are often documented in separate groups. Not all endpoints contain each type of parameter.

Example of parameters

The following screenshot shows a sample of parameters with the Box API:

In this example, the parameters are grouped by type: path parameters, query parameters, and body parameters. The endpoint also sets off the path parameter (collab_id) in an recognizable way.

Listing parameters in a table

Many times parameters are listed in a simple table or definition list like this:

Parameter Required/Optional Data Type
format Optional String

Here’s an example from Yelp’s documentation:

Yelp parameters

You can format the values in a variety of ways (aside from a table). If you’re using a definition list or other non-table format, be sure to develop styles that make the values easily readable.

Four types of parameters

REST APIs have four types of parameters:

  • Header parameters: Parameters that are included in the request header, usually related to authorization.
  • Path parameters: Parameters that appear within the path of the endpoint, before the query string (?). These are usually set off within curly braces.
  • Query string parameters: Parameters that appear in the query string of the endpoint, after the ?.
  • Request body parameters: Parameters that are included in the request body. Usually submitted as JSON.

The terms for each of these parameter types comes from the OpenAPI specification, which defines a formal specification that includes descriptions of each parameter type (see the Path object tutorial). Using industry standard terminology helps you develop a vocabulary to describe different elements of an API.

What to note in parameter documentation

Regardless of the parameter type, consider noting the following:

Data types for parameters

Because APIs may not process the parameter correctly if it’s the wrong data type or wrong format, it’s important to list the data type for each parameter. This is usually a good idea with all parameter types but is especially true for request body parameters, since these are usually formatted in JSON.

These data types are the most common with REST APIs:

  • string: An alphanumeric sequence of letters and/or numbers
  • integer: A whole number — can be positive or negative
  • boolean: True or false value
  • object: Key-value pairs in JSON format
  • array: A list of values

There are more data types in programming, and if you have more specific data types that are important to note, be sure to document them. In Java, for example, it’s important to note the data type allowed because Java allocates memory space based on the size of the data. As such, Java gets much more specific about the size of numbers. You have a byte, short, int, double, long, float, char, boolean, and so on. However, you usually don’t have to specify this level of detail with a REST API. You can probably just write “number.”

Max and min values for parameters

In addition to specifying the data type, the parameters should indicate the maximum, minimum, and allowed values. For example, if the weather API allows only longitude and latitude coordinates of specific countries, these limits should be described in the parameters documentation.

Omitting information about max/min values or other unallowed values is a common pitfall in docs. Developers often don’t realize all the “creative” ways users might use the APIs. The quality assurance team (QA) is probably your best resource for identifying the values that aren’t allowed, because it’s QA’s job to try to break the API.

When you test an API, try running a endpoint without the required parameters, or with the wrong parameters, or with values that exceed the max or min amounts. See what kind of error response comes back. Include that response in your status and error codes section. I get deeper with the importance of testing in Testing your docs.

Header parameters

Header parameters are included in the request header. Usually, the header just includes authorization parameters that are common across all endpoints and thus is not documented with each endpoint. Instead, the authorization parameters are documented in the authorization requirements section.

However, if your endpoint requires specific parameters to be passed in the header, you would document them in the parameters documentation here. (For more on request and response headers, see the curl tutorial where we explored this with some examples.)

Path parameters

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

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

Path parameters are usually set off with curly braces, but some API doc style’s precede the value with a colon or use other syntax. When you document path parameters, indicate the default values, the allowed values, and other details.

Color coding the path parameters

When you list the path parameters in your endpoint, it can help to color code the parameters to make them more easily identifiable. This makes it clear what’s a path parameter and what’s not. Through color you create an immediate connection between the endpoint and the parameter definitions.

For example, you could color code your parameters like this:

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

Optionally, you could also use the same color for the parameters in your documentation:

URL Parameter Description
user Here's my description of the user parameter.
bicycles Here's my description of the bicycles parameter.

By color coding the parameters, it’s easy to see the parameter in contrast with the other parts of the endpoint.

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.

However, with path parameters, order does matter. If the parameter is part of the actual endpoint (not added after the query string), then you usually describe this value in the description of the endpoint itself.

Request body parameters

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.

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 a number of key-value pairs, like this:

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

Documenting complex request body parameters

Documenting JSON data (both in request body parameters and responses) is actually one of the trickier parts of API documentation. Documenting a JSON object is easy if the object is simple, with just a few key-value pairs at the same level. But if you have a JSON object with multiple objects inside objects, numerous levels of nesting, and lengthy conditional data, it can be tricky. And if the JSON object spans more than 100 lines, or 1,000, you’ll need to carefully think about how you present the information.

Tables work all right for documenting JSON, but in a table, it can be hard to distinguish between top-level and sub-level items. The object that contains an object that also contains an object, and another object, etc., can be confusing to represent.

By all means, if the JSON object is relatively small, a table is probably your best option. But there are other approaches that designers have taken as well.

Take a look at eBay’s findItemsByProduct resource. Here’s the request body parameter (in this case, the format is XML):

eBay parameters

Below the request body parameter is a table that describes each parameter:

eBay parameters

But the sample request also contains links to each of the parameters. When you click a parameter value in the sample request, you go to a page that provides more details about that parameter value, such as the ItemFilter. This is likely because the parameter values are more complex and require more explanation.

The same parameter values might be used in other requests as well, so organization approach facilitates re-use. Even so, I dislike jumping around to other pages for the information I need.

Swagger UI’s approach for request body parameters

Swagger UI, which we explore later and also demo, provides another approach for documenting the request body parameter. Swagger UI shows the request body parameters in the format that you see below. Swagger UI lets you toggle between an “Example Value” and a “Model” view for both responses and request body parameters.

See the Swagger Petstore to explore the demo here. The Example Value shows a sample of the syntax along with examples. When you click the Model link, you see a sample request body parameter and any descriptions of each element in the request body parameter.

The Model includes expand/collapse toggles with the values. (The Petstore demo doesn’t actually include many parameter descriptions in the Model, but if any descriptions that are included, they would appear here in the Model rather than the Example Value.)

In a later section, I dive into Swagger. If you want to skip there now, go to Introduction to Swagger.

You can see that there’s a lot of variety in documenting JSON and XML in request body parameters. There’s no right way to document the information. As always, choose the method that depicts your API’s parameters in the clearest, easiest-to-read way.

If you have relatively simple parameters, your choice won’t matter that much. But if you have complex, unwieldy parameters, you may have to resort to custom styling and templates to present them clearly. I explore this topic in more depth in the Response example and schema section.

Parameters for the surfreport endpoint

For our new surfreport resource, let’s look through the parameters available and create a table describing the parameters. Here’s what my parameter information looks like:

Parameters

Path parameters

Path parameter Description
{beachId} Refers to the ID for the beach you want to look up. All Beach ID codes are available from our site at sampleurl.com.

Query string parameters

Query string parameter Required / optional Description Type
days Optional The number of days to include in the response. Default is 3. Integer
units Optional Options are either imperial or metric. Whether to return the values in imperial or metric measurements. Imperial will use feet, knots, and fahrenheit. Metric will use centimeters, kilometers per hour, and celsius. metric is the default. String
time Optional If you include the time, then only the current hour will be returned in the response. Integer. Unix format (ms since 1970) in UTC.

Even if you use Markdown for docs, you might consider using HTML syntax with tables. You usually want the control over column widths to make some columns wider or narrower. Markdown doesn’t allow that granular level of control. With HTML, you can use a colgroup property to specify the col width for each column.

Next steps

Now that we’ve documented the parameters, it’s time to show a sample request for the resource.

22% Complete

22/91 pages complete. Only 69 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285