The document discusses the relationship between APIs and their documentation, emphasizing the need to avoid redundancy in development and documentation processes. It highlights different approaches to API documentation, including static contracts like Open API Specification and dynamic profiles such as ALPS, while considering the target audience and organizational constraints. The document concludes with key questions to guide the selection of the best API documentation options.

2. Don’t repeat yourself - Your
API is your Documentation
Michael Hibay, Baysong Services

3. Before we begin…

4. Have you seen docs like this?

5. What about this?

6. This one?

7. Or this one?

8. Maybe this one?

9. What is the goal of ..
• An API?
– Expose the resources, capabilities, and constraints of
a system to machines.
• Documentation?
– Expose the resources, capabilities, and constraints of
a system to people.

10. Notice anything?
API
Audience:
Machines
Everything
else.
Documentation
Audience:
Humans
Everything
else.

11. Don’t Repeat Yourself
• “If I have to do a task a third time, I will do ten
times more work to never do it again.”

12. A common agile dilemma
• Deliver complex new API for widgets.
– Design ➔ Implementation
– Design ➔ Documentation
– Documentation & Implementation ➔ Consumption
– All of the above ➔ Validation
• You have one week.

13. Silo + Redundancy = Problem
• Break up the silo and Problem = Redundancy
• How do we fix it?
– Stagger the work in multiple sprints.
– Overwork the team and risk burnout.
– Find out if we could remove the redundancy.

14. What if Design = Documentation?
Documentation
Implementation Validation Consumption

15. How can we remove the redundancy?
• Static Contract
– Open API Specification (OAS)
• Dynamic Profile
– Application Level Profile Semantics (ALPS)
• JSON-LD + Schema.org
– Hydra

16. Static Contract
• OAS
– Concise descriptive format with little redundancy
– Contract tightly couples consumers to servers, and
protocols
– High difficulty pushing changes to contract or
representations

17. Dynamic Profile
• ALPS + JSON Home + Hypermedia
• Unfamiliar design concept
• Underdeveloped tooling
• Difficulty Consuming

18. ALPS
• Application Level Profile Semantic (ALPS)
– Domain Model drives Interaction
– Externally bound to protocols
– Dynamic and cacheable

19. JSON Home
• Dynamically discover
– Resources
– Documentation
– Hints

20. Hypermedia Formats
• Siren
– Library support, tight HTML coupling, not finalized
• HAL
– Library and tooling support, format ambiguities exist
• {json:api}
– Library support, light on hypermedia tooling.

21. JSON-LD + Schema.org
• Static contexts and definitions created to graph.
• Embeddable and Interoperable.
• Verbose and Global.
• Resistant to change.

22. Hydra
• Adds vocabulary for hypermedia driven design.
• Simplifies implementation of JSON-LD.
• Fundamentally assumes creation and use of
perfect vocabularies

23. Key Questions
• Use these questions to narrow in on the best
option for you. Analyze with these properties in
mind.
– Desired service longevity
– Consumption audience
– Organizational processes and policies

24. How long will this API run ____?
• Between versions
• Between breaking changes
• Until EOL

25. Will this API be used outside ____?
• Our team
• Our organization

26. Will we ___ control the client ecosystem?
– Directly
– Indirectly
• How much of our resources do we want to
commit to supporting consumer agents?

27. Do we have barriers to interactive docs?
• Organizational Processes?
• Regulatory constraints?
• Confidentiality constraints?

28. Can we help improve standards?
• OAS
• Hypermedia
• _______

29. Thank you!
• Any questions?

30. Contacts
• @hibaymj
• Blog
• Github
• LinkedIn