Post on 15-Feb-2017
New trends
● APIs for non-technical people
● 3rd-party integrations
● API flows
● IoA - Internet of APIs
Human-readable docs
Method characteristics
Arguments
Response description
Method
Method description
required?Argument type
Response type
Response description
Response description
Machine-readable docs
API version
Supported protocols
Method
Method description
Link to response description
required?
Argument type
API characteristics
Method characteristics
Response
Arguments
Would it be nice?
● All API descriptions in one place
● Documented in one format
● Anyone can add/improve API description
What does APIs.guru do?
● Filter out private and non-reliable APIs.
● Convert different formats into Swagger 2.0
● Fix mistakes, ~80% of spec have them
● Add additional data, like: logo, categories, …
● Update specs on daily basis
Road map
● Minimal valuable set of APIs - Done
● Grow number of integrations - In progress
● Collaborate with API owners - In progress
● Build community - Need your help:)
Data incompatibility
{ “First name”: “John”, “Surname”: “Smith”}
{ “Name”: “John”, “Surname”: “Smith”}
{ “Full name”: “John Smith”}
Schema incompatibility{ “properties”: { “First name”: { “type”: “string” }, “Surname”: { “type”: “string” } }}
{ “properties”: { “Name”: { “type”: “string” }, “Surname”: { “type”: “string” } }}{
“properties”: { “Full name”: { “type”: “string” } }}
Stage 1: Scalar types
{ “properties”: { “First name”: { “type”: “string” } “Surname”: { “type”: “string” } }}
{ “properties”: { “First name”: { “$ref”:
“http://apis.guru/types/name#” } “Surname”: { “$ref”:
“http://apis.guru/types/surname#” } }}
Stage 2: Complex types
{ “properties”: { “First name”: { “$ref”: “http://apis.guru/ types/name#” }, “Surname”: { “$ref”: “http://apis.guru/ types/surname#” } }}
{ “$ref”: “http://apis.guru/ types/fullname/15#”}
Stage 3: type converters
function (data) { return { “Full name”: data[“First name”] + data[“Surname”] };}
{ “First name”: “John” “Surname”: “Smith”}
{ “Full name”: “John Smith”}