apidays LIVE Helsinki & North: API Ecosystems - Connecting Physical and Digital March 16 & 17, 2022 Building an Accessible API Spec with Traditional Engineering Teams Griffin Solot-Kehl, Developer Advocate at Dolby Laboratories

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 2 D O L B Y

2. Hi, I’m Griffin
• Dolby.io
• Media enhancement and analysis APIs
• Real time communications APIs
• Millicast Low Latency Streaming
• 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 2 D O L B Y

3. 3
You need to work on
your API Spec.
© 2 0 2 2 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 2 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 2 D O L B Y

7. 7
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

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

9. 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
9
© 2 0 2 2 D O L B Y
@WINGOFAGRIFFIN

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

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

12. 12
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

13. 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
13
© 2 0 2 2 D O L B Y
@WINGOFAGRIFFIN

14. 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
• Can use tools like Notion, Jira, Asana, etc. to organize
14
© 2 0 2 2 D O L B Y
@WINGOFAGRIFFIN

15. 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
15
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

16. Example: Dolby.io Media + 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.
16
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

17. Example: Dolby.io Communications
• 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
17
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

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

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

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

21. © 2 0 2 2 D O L B Y
@WINGOFAGRIFFIN