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.
In the early years of specifications, there was healthy competition between the formats. But now, without a doubt the OpenAPI specification is the most popular, with the largest community, momentum, and tooling. Because of this, I spend the most time on OpenAPI. In fact, this entire section focuses on the OpenAPI specification. (I moved the RAML and API Blueprint pages into the Resources section at the end.)
“OpenAPI” refers to the specification, while “Swagger” refers to the API tooling that reads and displays the information in the specification. I’ll dive into both OpenAPI and Swagger in much more depth in the pages to come.
Overall, specifications for REST APIs lead to better documentation, tooling, and structure with your API documentation.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. (This is why I created an entire section of non-reference or user guide topics.)
Nevertheless, the reference documentation the specification covers often constitutes the core value of your API, since it addresses the endpoints and what they return.
Writing to a specification introduces a new dimension to documentation that makes API documentation substantially unique. By mastering the OpenAPI specification format, you can distinguish yourself in significant ways from other technical writers.
54/107 pages complete. Only 53 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.