AsyncAPI Governance the easy way

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