Overview of REST API specification formats
When I introduced REST APIs, I mentioned that REST APIs follow an architectural style, not a specific standard. However, there are several REST specifications that have been developed to try to provide some standards about how REST APIs are described. The three most popular REST API specifications are as follows: OpenAPI (formally called Swagger), RAML, and API Blueprint.
By far, the OpenAPI specification is the most popular, with the largest community, momentum, and history. Because of this, I spend the most time on OpenAPI here. Overall, these specifications for REST APIs lead to better documentation, tooling, and structure with your API documentation.
“OpenAPI” refers to the specification, while “Swagger” refers to the API tooling that reads and displays the information in the specification.
- Should you use one of these specifications?
- Separate outputs from other docs
- Video presentation of this section
Should you use one of these specifications?
In a survey on API documentation, I asked people if they were automating their REST API documentation through one of these standards. About 30% of the people said yes.
In my opinion, these specifications should certainly be used, as they not only lead to predictable, industry-consistent experiences for users of your APIs, they also force you to standardize on API terminology and give users a way to learn by doing as they try out the endpoints with real parameters and data.
Most of all, the specifications give you a template to fill out with your API. This template makes it clear what information you need, how you organize and structure the information, and other details. This kind of template, standardized and highly valued within the API community, won’t pit you against your engineers as you negotiate which terms to use and what users really need.
For an excellent overview and comparison of these three REST specification formats, see Top Specification Formats for REST APIs by Kristopher Sandoval on the Nordic APIs blog.
Keep in mind that these REST API specifications mostly describe the reference endpoints in an API. While the reference topics are important, you will likely have a lot more documentation to write in addition to the reference endpoints.
The bulk of documentation often explains how to use the endpoints together to achieve specific goals, how to configure the services that use the endpoints, how to deploy the services, what the various resources and rules are, how to get an API key, throttling limits, and so forth. It’s hard to include all of this information into the specification alone. Nevertheless, the documentation the specification provides often constitutes the core value of your API, since it addresses the endpoints and what they return.
Separate outputs from other docs
If you choose to automate your documentation using one of these specifications, it likely will be a separate site that showcases your endpoints and provides API interactivity. You’ll still need to write many more pages of documentation about how to actually use your API.
Having multiple documentation outputs (rather than one seamless whole) presents a challenge when creating and publishing API documentation. I explore this challenge in more depth in Integrating Swagger UI with the rest of your docs.
Video presentation of this section
For a video presentation of this section of the course, see the following:
This was a presentation I gave to the STC/WTD San Diego chapter on February 18, 2018. (More details are here.)
56/96 pages complete. Only 40 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.