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 an 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 talk more about the importance of testing in Testing your docs.
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. Instead, the authorization details in header parameters are documented in the authorization requirements section.
However, if your endpoint requires unique parameters to be passed in the header, you would document them in the parameters documentation within each endpoint.
Path parameters are part of the endpoint itself and are not optional. For example, in the following endpoint, and are required path parameters:
Path parameters are usually set off with curly braces, but some API doc styles precede the value with a colon or use a different 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. Color coding the parameters 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:
You could then use the same color for these parameters in later descriptions:
|user||Here’s my description of the user parameter.|
|bicycleId||Here’s my description of the bicycles parameter.|
By color coding the parameters, it’s easy to see the parameter being defined and how it relates to the endpoint definition.
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.
would return the same result.
However, with path parameters, the order does matter. If the parameter is part of the actual endpoint (not added after the query string), 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/. But in the body of the request, you might include a JSON object with many key-value pairs, like this:
Documenting complex request body parameters
Documenting JSON data (both in request body parameters and responses) is 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 think carefully 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):
Below the request body parameter is a table that describes each parameter:
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. The separate page with more detail is likely because the parameter values are more complex and require detailed explanation.
The same parameter values might be used in other requests as well, so eBay’s approach likely facilitates re-use. Even so, I dislike jumping around to other pages for the information I need.
Swagger UI’s approach to request body parameters
Swagger UI, which we explore later and also demo, provides another approach to 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.
The Model includes expand/collapse toggles with the values. (The Petstore demo doesn’t include many parameter descriptions in the Model, but if you include descriptions, they would appear here in the Model rather than in the Example Value.)
We’ll get into Swagger in much more detail in Introduction to the OpenAPI specification and Swagger. For now, focus on these core elements of API reference documentation. You will see these same sections appear in the OpenAPI specification.
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 more 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:
|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|
|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.
Now that we’ve documented the parameters, it’s time to show a sample request for the resource.
29/114 pages complete. Only 85 more pages to go.
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.