Search results

Overview of REST API specification formats

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

If you're an engineer, please take this quick survey focused on engineers who write documentation. This will help me better understand trends in this space. You can see the ongoing results here.

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 non-reference 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.

36% Complete

36/110 pages complete. Only 74 more pages to go.


Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.