Overview of REST API specification formats
I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.
When I introduced REST APIs, I mentioned that REST APIs follow an architectural style, not a specific standard. However, several REST specifications have been developed to try to provide standards in the way that 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 this course. In fact, this entire section focuses on the OpenAPI specification. (I moved RAML and API Blueprint into the Additional 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 conceptual topics.)
Nevertheless, the reference documentation that 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.
60/146 pages complete. Only 86 more pages to go.
Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.