1.
Self-Documenting APIs
@skwp
@reverbdotcom

2.
What Makes a
Good API?

3.
Discoverable

4.
Self Documenting

5.
Standardized

6.
Discoverability

7.
Discoverability
What can I do with it?

8.
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.

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

10.
Hypermedia as the Engine of Application State
HATEOAS

11.
What Happens When I
GET reverb.com/api?

12.
What Happens When I
GET yahoo.com?

13.
curl https://reverb.com/api

14.
GET product._links.buy

15.
Evolvability

16.
Self-Documenting

17.
Self-Documenting
How can I do what I want to do?

18.
Minimize
Documentation Drift

19.
Generate Docs, Clients, even Servers from Code

20.
Standardized

21.
Standardized
How is it similar to other APIs?

22.
Simplicity Increases
Likelihood of Adoption

23.
Fewer Constructs is
Simpler

24.
Siren • jsonapi.org • HAL

25.
Siren • jsonapi.org • HAL

26.
Siren • jsonapi.org • HAL

27.
Winner: HAL
http://stateless.co/hal_specification.html

28.
BONUS - Baked into Roar

29.
Discoverable
✓HATEOAS
✓HAL Links
✓Grape+Roar

30.
Self Documenting
✓Swagger
✓Grape-Swagger
✓Swagger-UI

31.
Standardized
✓Swagger
✓HAL
✓REST

32.
Resources
http://swagger.io/
https://github.com/swagger-api/swagger-spec
http://api.opensupporter.org/hb2/browser.html#/api/v1
http://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