API Definitions: What Is Behind The Name?

Last week at #APIStrat Amsterdam, I moderated, and presented in a session that was called API service descriptions. I gave the talk for the first 15 minutes, then Sumit Sharma (@sumitcan), Ole Lensmar (@olensmar), and Ruben Verborgh (@RubenVerborgh) followed me-- the full video is on Youtube if you are interested.

Over the last couple months I've been doing a deeper dive into the area of API design, with a specific look at API definition formats from API Blueprint, RAML and Swagger, so the session was intended to help me continue the conversation, in person, on the stage at #APIStrat Amsterdam. I'm happy I did, because Ole came to the table with some valuable data on API definitions, that save me some valuable research hours.

I'm breaking up his work into several smaller posts, you can find his full deck on slideshare, first up is a comparison overview of each API Blueprint, RAML and Swagger:

 

API-Blueprint

RAML

Swagger

Format

Markdown

YAML

JSON

Spec License

MIT

ASL 2.0 / TM

ASL 2.0

Available at

GitHub

GitHub

GitHub

Sponsored by

Apiary

Mulesoft

Reverb

Current Version

1A3

0.8

1.2

Initial commit

April, 2013

Sep, 2013

July, 2011

Commercial Offering

Yes

Yes

No

API Design Approach

Top-down

Top-down

Bottom-up

Ole provides a nice overview of the three leading API definition formats, giving API providers a good side-by-side summary that can be used when deciding which format to support. I will work with Ole to help keep the numbers up to date, and include in my final research white paper for API design when finished.

Thank you too Ole Lensmar (@olensmar) and Smartbear Software for doing this research, and allowing me to share it with you.