apidays Paris 2022 - OpenAPI: An Early Design Feedback Engine, Lukas Rosenstock, Author

apidays Paris 2022 - APIs the next 10 years: Software, Society, Sovereignty, Sustainability
December 14, 15 & 16, 2022

OpenAPI: An Early Design Feedback Engine
Lukas Rosenstock, Author

------

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

Transcript

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