The document discusses the importance of designing APIs alongside developing good documentation and a developer portal, emphasizing collaboration among various stakeholders. It outlines the role of OpenAPI as a single source of truth and offers a GitHub-based workflow for managing changes and reviews. Additionally, it suggests incorporating automated tests and mock servers for early feedback to improve the development process and enhance the user experience.

1. OpenAPI:
An Early Design Feedback Engine
Lukas Rosenstock

2. 2023 SERIES OF EVENT
New York
May 16&17
Australia
October 11&12
Singapore
April 12&13
Helsinki & North
June 5&6
Paris
SEPTEMBER
London
November
15&16
June 28-30
SILICON VALLEY
March 14&15
Dubai & Middle East
February 22&23

3. machine-readable
YAML file =
Single Source of Truth
Manual
Writing
Visual
Tools
API
Design
Docs
Reference
Code
Stubs & SDKs;
Input/Output
Validation
Tests &
Monitoring
Code
+ annotations

4. Design > Documentation

5. Design > Documentation > DevPortal

6. Bad Design:
Documentation as
“Damage Control”
Bad Documentation:
DevPortal can only be as
good as its content

7. Good Design + Good Documentation
+ Good DevPortal = 😀😀😀

8. Design ➡️ Documentation ➡️ DevPortal

9. How to design an API?

10. What are
the APIs
use cases?
Which data
shall we
expose?
Who are our
developer
personas?
Will this API be a
monetized product?
How does the API
fit in our existing
ecosystem?

11. Involve all
stakeholders
(Product Owner, Developers, QA, Subject Matter
Experts, Business Analysists, Enterprise
Architects, Technical Writers, Developer
Advocates & Developer Success Roles …)
Talk about personas, use
cases etc. before writing
an OpenAPI definition

13. Change is inevitable!

14. We should discuss
preparing for an
upcoming business
requirement …
I think we completely
forgot the DELETE
endpoint.
Adding this field to the user
collection endpoint would
make my frontend code more
efficient.
This would be difficult to
explain in documentation.
Why not try something
else?

15. This meeting should have been an email
a change management system

16. Requirements
• Single Source of Truth
• Suggest and compare changes
• Build consensus
• Review what changed

18. Docs-as-Code 🤔

19. OpenAPI = Docs (+ X)

20. GitHub Workflow
• Single Source of Truth ➡️ definition repository‘s main branch
• Suggest and compare changes ➡️ pull requests
• from stakeholder branch
• Build consensus ➡️ accept and merge pull requests
• Review what changed ➡️ commit history / diff

22. Review of Changes
• Is this clear or needs
discussion/research?
• Does the change make sense?
• Is it breaking?

24. Early Feedback Mechanism 1:
Stakeholder Review in Git(Hub)

25. Will/can every stakeholder
use Git(Hub)?! 🤔

26. CI/CD Pipeline (e.g. GitHub Actions)
• Check your API definition to ensure it‘s always valid
• Well-formed API follow custom rules (API guidelines)
• Tools: Spectral etc.
• Run automated tests to keep implementation and definition in sync
• Set up a mock server to serve static API responses
• Generate documentation (e.g. Redoc/Swagger) and publish it

27. Early Feedback Mechanism 2:
The (internal) DevPortal

28. Pipeline
Repository
API
Stakeholders
DevPortal

29. Using the DevPortal prior to implementation
• (Internal) Developers can review upcoming APIs
• Even test with mock server
• Easier access/UI compared to Git(Hub)
• Required: alternate feedback process
• Documentation Preview on DevPortal
• Think API backend implementation and developer experience together
• Build up interest prior to release

30. Repository
inner circle of stakeholders
DevPortal
outer circle of stakeholders

31. Shameless plug:

32. Feedback?!
• Twitter: @LukasRosenstock
• Mastodon/Fediverse: @lukas@indieweb.social
• E-Mail: lukas@rosenstock.email