The document discusses best practices for building accessible API specifications within engineering teams, highlighting common issues such as unclear documentation and technical debt. It suggests maintaining a modular specification, emphasizing clear communication, using tools for inspection, and gathering user feedback. The presentation underscores the importance of agile techniques and constant collaboration to improve API usability.

1. Building an Accessible
API Spec with Traditional
Engineering Teams
Griffin Solot-Kehl
Developer Advocate, Dolby.io
@WingofaGriffin
1
© 2 0 2 0 D O L B Y | C O N F I D E N T I A L
© 2 0 2 1 D O L B Y

2. Hi, I’m Griffin
• Dolby.io
• Media enhancement and analysis APIs
• Real time communications APIs
• Developer Advocate in REST APIs >3 years
• From baby startups to big corporations
• Focus on API integrations
• Spent a LOT of time on docs pages
2
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

3. 3
You need to work on
your API Spec.
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

4. Common Issues:
• Unclear/Out of Date documentation
• Hard to update existing OpenAPI Spec
• Inconsistent parameters across endpoints
• Slow process to communicate changes
• Internally
• Externally
• Less of an issue with API first development
4
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

5. 5
What can we do?
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

6. Keeping a Modular Spec
• Don’t rewrite identical code
• $ref objects
• Identify patterns in new endpoints
• Use helper files
• “Global” variables to reuse
• Document what they do!
• Comment often!
swagger.io/docs/specification/using-ref/
6
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

7. Authentication
• Security vs. Simplicity
• OAuth2 Tokens
• Key Management
• Rotation tools
• Have a “validate” API endpoint
7
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

8. Keep it Simple (Stupid)
• Clear how to create, clear what the response is
• Expectations between user levels
• Label and Organize JSON well
• Encourage use of tools like jq
• Consistent Parameters
8
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

9. • Previous Employers
• Internal Docs
• Existing 3rd party APIs in stack
• Competitor Docs
Examples of Quality Docs
9
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

10. Documentation
• Verify valid OpenAPI Spec
• Readme.com, Redoc.ly, DapperDox,
WidderShins, SwaggerUI, etc.
• Ensure public facing endpoints work!
• Autogenerate Sample Code
• Make calls within website
10
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

11. Technical Debt
• Hard to change existing infrastructure
• But it will get even harder as you let it accumulate
• Turns off new users
• Existing customers will be poached
• Security vulnerabilities
11
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

12. Think Agile!
• Use Project Management techniques to get user stories
• Scrum Masters can be useful!
• As a ___ I want to ___ so I can ___
• Create goals to chuck out the technical debt
• Divide tasks into subcategories for small wins over a long period of time
12
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

13. Dogfooding!
• Make engineers use the API!
• Internal tools
• Other teams’ feedback
• Utilize the DevRel team (if applicable)
• Gather trusted user feedback
• Addition to automated testing
13
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

14. Example: Dolby.io + Box
• Enhance API used on every audio project
• Upload to Box, enhance inside
• Videos, podcasts, audio files
• Python, JS, Shell, etc. options as alternatives
• Also see Transcode, Mastering, etc.
14
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

15. Example: Dolby.io CAPI
• Communications API used for Video Calls
• Expose average user workflow
• Find common use cases
• Add “nice to have” features
• Devs get curious when quirks happen live
15
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

16. 16
Everything is a
Work in Progress
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

17. 17
Constant
Communication
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

18. Thank you!
@WINGOFAGRIFFIN
DOLBY.IO
18
© 2 0 2 1 D O L B Y

19. © 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN