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
