"If you find yourself maintaining a set of documents explaining the use of your API, you haven't finished it's design yet. This talk will compare various strategies with examples, while discussing ways to determine the most appropriate method for your API. We will explore OAS (Swagger), Json-LD, Schema.org, HAL, Hydra, Siren, Semantic profiles, and other formats while comparing their relative strengths and weaknesses. After these options, we will arm you with a series of questions which direct you to the appropriate tool for your API. Discover how you can save considerable time and headaches by incorporating a self documenting method in your API design."

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