INTERFACE, by apidays - APIs: the next 10 years June 8, 9 & 10 2022 Building an Accessible API Spec with Traditional Engineering Teams Griffin Solot-Kehl, Developer Advocate at Dolby Laboratories ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

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. 2022 SERIES OF EVENTS
New York
JULY
(HYBRID)
Australia
SEPTEMBER
(HYBRID)
Singapore
APRIL
(VIRTUAL)
Helsinki & North
MARCH
(VIRTUAL)
Paris
DECEMBER
(HYBRID)
London
OCTOBER
(HYBRID)
Hong Kong
AUGUST
(VIRTUAL)
JUNE (VIRTUAL)
India
MAY
(VIRTUAL)
APRIL (VIRTUAL)
Dubai & Middle East
JUNE
(VIRTUAL)
Check out our API Conferences
www.a pida ys .globa l
Want to talk at one of our conferences?
apidays.typeform.com/to/ILJeAaV8

3. Hi, I’m Griffin
• Dolby.io
• Media enhancement and analysis APIs
• Real time communications APIs
• Millicast Low Latency Streaming
• Developer Advocate in REST APIs >4 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

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

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

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

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

8. Use a Linter!
• Facilitates consistency
• Validates description
• Supports many languages
• Can even integrate into your IDE
• Spectral, redocly, IBM Validator, etc.
• https://openapi.tools/
• Take note of supported versions!
• Also source for other cool tools
7
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

9. 8
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

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

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

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

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

14. 13
@WINGOFAGRIFFIN
© 2 0 2 2 D O L B Y

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

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

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

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

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

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

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

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

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