The API Evangelist API Definition Guide
10 May 2016
How we define our APIs has dramatically changed in recent years. Since Swagger came onto the scene around five years ago, there has been a rapid growth in the number of open formats, tooling, and services to help us define APIs. Companies are using API definitions like OpenAPI Spec, Postman, and API.json to communicate about their APIs at almost every stop along the API life cycle. This is my research to better understand all the moving parts in this fast growing sector.
This guide focuses on API definition formats like OpenAPI Spec and API Blueprint, as well as schema formats like JSON Schema, and MSON, but I also touch on media types, link relations and other common building blocks for defining our APIs so they speak a common language. While there is some open tooling included in this guide, I'm trying to focus on the specifications, and formats themselves, and help make sense of the amount of information available to us.
I fund my research through consulting, selling my guides, and the generous support of my sponsors. I appreciate your support in helping me continue with my work and hope you find it relevant in your API journey.