API governance for AsyncAPI

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: Is the document valid? •Level 1: Does it meet basic (compliance) standards? •Level 2: Is it consistent with the rest of the API? •Level 3: Is it a joy to work with? @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 v1.2 and later has support for linting AsyncAPI @redocly ~ @lornajane

Lint AsyncAPI LED wall: https://github.com/magicmonkey/ledwall @redocly ~ @lornajane

Lint AsyncAPI LED wall: https://github.com/magicmonkey/ledwall @redocly ~ @lornajane

Lint AsyncAPI Configure the tool rules: spec: error channels-kebab-case: error Run the command: $ redocly lint ledwall.yaml validating ledwall.yaml… ledwall.yaml: validated in 5ms Woohoo! Your API description is valid. @redocly ~ @lornajane

Good API governance (without tears) @redocly ~ @lornajane

Resources •https://lornajane.net •https://redocly.com •https://www.asyncapi.com/tools •https://github.com/magicmonkey/ledwall @redocly ~ @lornajane