This document discusses key aspects of self-documenting APIs, including discoverability, evolvability, and standardization. It recommends using HATEOAS and HAL links to make APIs discoverable, Swagger and Grape-Swagger to make them self-documenting, and standards like Swagger, HAL, and REST to make them standardized. Following these practices helps ensure APIs are easy to use, adapt to changing needs, and consistent with other APIs.

1. Self-Documenting APIs
@skwp
@reverbdotcom

3. What Makes a
Good API?

4. Discoverable

5. Self Documenting

6. Standardized

7. Discoverability

8. Discoverability
What can I do with it?

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

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

11. Hypermedia as the Engine of Application State
HATEOAS

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

13. What Happens When I
GET yahoo.com?

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

15. GET product._links.buy

18. Evolvability

19. Self-Documenting

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

21. Minimize
Documentation Drift

22. Generate Docs, Clients, even Servers from Code

25. Standardized

26. Standardized
How is it similar to other APIs?

27. Simplicity Increases
Likelihood of Adoption

28. Fewer Constructs is
Simpler

29. Siren • jsonapi.org • HAL

30. Siren • jsonapi.org • HAL

31. Siren • jsonapi.org • HAL

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

33. BONUS - Baked into Roar

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

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

36. Standardized
✓Swagger
✓HAL
✓REST

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