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
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
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
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?
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
21.
22. Review of Changes
• Is this clear or needs
discussion/research?
• Does the change make sense?
• Is it breaking?
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
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