Self-Documenting APIs

@skwp@reverbdotcom

What Makes a Good API?

Discoverable

Self Documenting

Standardized

Discoverability

DiscoverabilityWhat can I do with it?

If the engine of application state (and hence the API) is

not being driven by hypertext, then it cannot be

RESTful and cannot be a REST API. Period.

http://martinfowler.com/articles/richardsonMaturityModel.html

Hypermedia as the Engine of Application StateHATEOAS

What Happens When I GET reverb.com/api?

What Happens When I GET yahoo.com?

curl https://reverb.com/api

GET product._links.buy

Evolvability

Self-Documenting

Self-DocumentingHow can I do what I want to do?

Minimize Documentation Drift

Generate Docs, Clients, even Servers from Code

Standardized

StandardizedHow is it similar to other APIs?

Simplicity IncreasesLikelihood of Adoption

Fewer Constructs is Simpler

Siren • jsonapi.org • HAL

Siren • jsonapi.org • HAL

Siren • jsonapi.org • HAL

Winner: HALhttp://stateless.co/hal_specification.html

BONUS - Baked into Roar

Discoverable✓HATEOAS

✓HAL Links✓Grape+Roar

Self Documenting✓Swagger✓Grape-Swagger✓Swagger-UI

Standardized

✓Swagger✓HAL

✓REST

Resourceshttp://swagger.io/

https://github.com/swagger-api/swagger-spec

http://api.opensupporter.org/hb2/browser.html#/api/v1http://stateless.co/hal_specification.html

https://github.com/swagger-api/swagger-ui

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

@skwp @reverbdotcom

https://github.com/swagger-api/swagger-codegen