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, next up after API Definitions: What Is Behind The Name?, is a side by side comparison of how Blueprint, RAML and Swagger each model REST:
|
API-Blueprint |
RAML |
Swagger |
|
|
Resources |
X |
X |
X (“api”) |
|
Methods/Actions |
X (“action”) |
X (“method”) |
X (“operation”) |
|
Query Parameters |
X |
X |
X |
|
Path/URL Parameters |
X |
X |
X |
|
Header Parameters |
X |
X |
X |
|
Representations (status codes, mime-types) |
X |
X |
X |
|
Documentation |
X |
X |
X |
|
Authentication |
Basic, Digest, Oauth 1&2, (*) |
Basic, API-Key, OAuth 2 |
|
|
Representation Metadata |
<any> (inline) |
<any> (inline/external) |
JSON Schema (subset) |
|
Nested Resources |
X |
X |
|
|
Composition/Inheritance |
Resource Models |
Traits, Resource Types |
|
|
File inclusions |
X |
||
|
API Version metadata |
X |
X |
|
|
Sample Representations |
X |
X |
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.
