A presentation at APIDays London in in London, UK by Lorna Jane Mitchell
API Governance for AsyncAPI Lorna Mitchell, Redocly @redocly ~ @lornajane
API governance Good API governance is invisible Without it: •designing changes is more difficult •changes get rejected and need repeat work •APIs become inconsistent •more difficult to adopt an API @redocly ~ @lornajane
@redocly ~ @lornajane
AsyncAPI and Governance AsyncAPI is complex! (it’s a feature, not a bug) •Many protocols •Often multiple API descriptions •Multiple tech stacks @redocly ~ @lornajane
Start with standards Written standards define your API identity. @redocly ~ @lornajane
Design good governance Start small, and formalise existing practices. Outputs are a written standards set, and linting rules. One size does not fit all! Consider mulitple standards and apply as appropriate @redocly ~ @lornajane
Designing rulesets •Level 0: Valid •Level 1: Compliant •Level 2: Consistent •Level 3: Delightful @redocly ~ @lornajane
Level 0: Valid Syntax is good and meets the AsyncAPI specification. •sounds basic •genuinely a good starting point •start here for winning workflows! @redocly ~ @lornajane
Level 1: Compliant Meets agreed API governance standards. •basic service design •metadata requirements (license, contact) •security is required •basic data types and formats, ISO standards @redocly ~ @lornajane
Level 2: Consistent Rigid rules about naming make healthy boundaries. •camelCase or kebab-case? •all plural, or all singlular •glossary for consistent naming @redocly ~ @lornajane
Level 3: Delightful Now add the rules that make things better! •examples required and useful •descriptions include rich explanations and links @redocly ~ @lornajane
Governance processes Change management, done well @redocly ~ @lornajane
Non-lintable standards The machines cannot do everything * Humans must review changes too •would you want to use this API? •is the naming sensible and intuitive? •is the change consistent with the existing API? * Try asking an AI “does this naming make sense?” @redocly ~ @lornajane
Reviews matter In software we can iterate. In published interfaces, that’s harder. Build an API council •Product specialists •Technical experts •Customer advocates (UX, tech writers, DevRel) @redocly ~ @lornajane
Tools for API Governance https://www.asyncapi.com/tools @redocly ~ @lornajane
Redocly CLI: AsyncAPI Redocly CLI •lint and bundle AsyncAPI descriptions •custom rules and plugins, including transform steps •support for AsyncAPI 2.6 and 3.0 @redocly ~ @lornajane
Good API governance (without tears) @redocly ~ @lornajane
Resources •https://redocly.com/docs/cli/guides/lint-asyncapi/ •https://lornajane.net •https://redocly.com •https://www.asyncapi.com/tools @redocly ~ @lornajane
Consistency is the cornerstone of an exceptional developer experience. In this session we will explore the world of asynchronous APIs and how describing them lays the foundation for measurement, control, and improvement.
Navigate the challenges of API governance and discover how to devise sane standards that support usability, security, reliability, and operability. Learn how automation and linting tools can streamline the development process and improve the quality of our work. Go beyond simple validation, and enforce essential characteristic such as specific protocols, naming conventions, data formats, and documentation requirements.
This session is for anyone working with data streaming and seeking to improve AsyncAPI platforms. Unleash the power of consistency and elevate your asynchronous APIs to new heights.
