apidays Paris 2024 - API Governance for EDA, Frank Kilcommins, SmartBear

API Governance for EDA: Unlocking Developer Experience with AsyncAPI
Frank Kilcommins, Principal API Technical Evangelist at SmartBear

apidays Paris 2024 - The Future API Stack for Mass Innovation
December 3 - 5, 2024

------

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/

Transcript

1. API Governance for EDA Unlocking Developer Experience with AsyncAPI
2. I’m Frank Kilcommins • Principal API Technical Evangelist @ SmartBear • Developer and Architect ( APIs & Developer Experience) • Governance Board member on the OpenAPI Initiative (OAI) • Co-Maintainer of the Arazzo Specification
3. Global Rise in API Production $17 trillion Global API economic impact by 2030 of businesses generate revenue via APIs 65% of businesses are using APIs 93% https://boomi.com/content/report/api-economy-2024/
4. More APIs increases landscape complexity Multi-Everything Multiple Gateways, multiple portals, multiple API styles, workflow variance. Distributed Collaboration Difficult to effectively collaborate across distributed team and diverse toolsets. Increasing API Portfolio An increasingly diverse API portfolio causes oversight and management challenges. More Specifications Additional specifications help address modern needs, but it increases the need for skilled practitioners.
5. More APIs hinders discoverability • No universal mechanism to discover APIs regardless of style or status • Difficult to apply quality checks and validate against standards • Difficult to evolve safely without breaking consumers • No ability to self-serve consumer onboarding • Rise in zombie APIs and inevitable security issues
6. More APIs means more security concerns 30% 60% APIs do not enforce any form of authentication Internet traffic generated by malicious bots Organizations suffered API breaches in the last 2 years 51% https://content.salt.security/state-api-report.html
7. Specifications can calm the chaos Design Reuse, linking, callbacks Mocking Prototyping Implementation Generated server code / models Deployment/Runtime Security, usage policies, monitoring, caching, rate-limiting, metrics etc. Clients Generated libraries Testing Functional, security, load, compliance etc. Virtualization Functional/Runtime, use-case simulations Documentation Developer Portals, code examples, user guides, support, etc. Note: it’s still possible to create horrible and/or factually incorrect documents
8. Alignment gap between expectations & reality 4% 12% 12% 27% 45% 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50% Strongly Disagree Strongly Agree Disagree Neutral Agree Our organization has good processes in place to ensure APIs can be consumed by others efficiently 2023 2021 5% 10% 16% 30% 38% 0% 10% 20% 30% 40% Strongly Disagree Strongly Agree Disagree Neutral Agree Our APIs are well documented for our API consumers 2023 2021 ▪ Only 48% are confident their API docs are well documented ▪ ~43% unsure their processes will deliver appropriate DX SmartBear – State of Software Quality | API 2023
9. Lack of standardization is the culprit • Standardization and security continue to rank as top challenges Top industry challenges for API producers 51% 40% 37% 39% 40% 34% 37% 20% 0% 10% 20% 30% 40% 50% 2019 2020 2021 2023 SmartBear – State of Software Quality | API 2023
10. We need fast collaborative feedback loops Consumer Team(s) if possible Provider Team R Requirements DESIGN Design Candidate Review Feedback API Standards, Style Guides, & Governance Rules (e.g., via Spectral) Standards & Regulatory Requirements Jira + Example Mapping Business & Security Stakeholders
11. Governance: Like it or not – you NEED it • Start small for visible quality and easier buy in • Don’t boil the ocean • Linting is an easy way to shift quality insights earlier in the process • Reuse information schemas across API styles • Start an API Catalog covering used API styles
12. Governance: Like it or not – you NEED it • Start small for visible quality and easier buy in • Don’t boil the ocean • Linting is an easy way to shift quality insights earlier in the process • Reuse information schemas across API styles • Start an API Catalog covering used API styles
13. Linting with Spectral – supports AsyncAPI v3 • Spectral CLI • Spectral VSCode extension • Spectral GitHub Action (v3 support coming soon) Thank you to the AsyncAPI core team for adding v3 ruleset!
14. AsyncAPI Core v3 Ruleset – 27 opinionated rules • asyncapi-parameter-description • asyncapi-unused-components-schema • asyncapi-unused-components-server • asyncapi-servers • asyncapi-3-server-no-empty-variable • asyncapi-3-server-no-trailing-slash • asyncapi-3-server-not-example-com • asyncapi-3-tag-description • asyncapi-3-tags-alphabetical • asyncapi-3-tags-uniqueness • asyncapi-3-tags • asyncapi-info-contact-properties • asyncapi-info-contact • asyncapi-info-description • asyncapi-info-license-url • asyncapi-info-license • asyncapi-3-channel-no-empty-parameter • asyncapi-3-channel-no-query-nor-fragment • asyncapi-3-channel-no-trailing-slash • asyncapi-3-channel-servers • asyncapi-channel-parameters • asyncapi-3-headers-schema-type-object • asyncapi-3-operation-description • asyncapi-3-payload-unsupported- schemaFormat • asyncapi-latest-version • asyncapi-3-document-resolved • asyncapi-3-document-unresolved Root Level Info Object Servers Object Channel(s), Operation(s), Messages Objects Tags Object Components Object
15. Quick Example: asyncapi-3-tags-uniqueness • Tags MUST NOT have duplicate names (identifiers).
16. Spectral: Getting started with AsyncAPI • Install Spectral CLI • Example: npm install -g @stoplight/spectral-cli • Install VSCode Extension • Create a .spectral.json or .spectral.yaml file • Leverage the core AsyncAPI ruleset extends: - "spectral:asyncapi"
17. Running Spectral with VS Code
18. Disabling rules until maturity increases • Draw a line in the sand, decide what rules to disable for existing APIs or until maturity increases. • Clearly document and communicate this information
20. Disable certain rules ONLY for AsyncAPI 2.x? • Not explicitly supported but…. file naming, glob patterns, and overrides help!
22. Custom Rules: Define your Golden Path • Improve consistency across your distributed teams • Improve descriptiveness of schemas, channels, operations, applications, etc. • Check for schema reuse • Highlight the power of examples
23. Most Important API Documentation Features • Examples continue to be the best learning resource SmartBear – State of Software Quality | API 2023
24. Most Important API Documentation Features • Examples continue to be the best learning resource SmartBear – State of Software Quality | API 2023
25. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
26. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
27. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
28. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
29. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
30. Adding Examples to AsyncAPI v3? • There are numerous places where rich examples can be added: • Server Variable Object • Parameter Object • Message Object • Message Trait Object • JSON Schema Objects / Arrays etc.
31. Custom Rules: Reduce the Bike-Shedding
32. Custom Rules: Reduce the Bike-Shedding €335,000 for a Bike Shed at Leinster House (Dail Eireann) – if only they got faster feedback!!
33. Custom Rules: Basic Anatomy • message - a message that’s displayed in output • given* - the part of the document to apply the rule on. • then* - what function to apply to given part of doc • core functions: falsy, truthy, pattern, casing, schema, defined, undefined, xor, enumeration, etc. • Define your own custom rules • severity - the severity of the rule (default: warn). Other options are `error`, `info`, `hint`, `off` * Required property
34. Custom Rules: How to add • Extend your .spectral.yaml
36. Custom Functions: When you need more juice • If the core functions aren't enough for your custom ruleset, Spectral allows you to write and use custom functions. • By default, Spectral looks for the functions/ folder.
37. Remember: Linting helps across the lifecycle IDE CLI CI/CD
38. Ingredients for ‘good’ Developer Experience? Discoverable (Developer Portal) Documentation • Easily findable • Self-service orientated • Credentials mgmt. • Mocks/Sandboxes • SDKs Design • Appropriate API style • Extensible • Usable • Secure by design • Leverage Specifications • Style guides • Human reviews Communication & Insights • Changelogs • Comms strategy • Non-breaking changes • Usage metrics • SLA / SLO insights • Reference • Concepts • Use case orientated • Code samples • Accurate • Consistent • Human reviews
39. Looking ahead: EDA use-case orientated Workflows
40. Resources • https://docs.stoplight.io/docs/spectral • https://marketplace.visualstudio.com/items?itemName=stoplight.spectral • https://github.com/marketplace/actions/spectral-linting • https://smartbear.com/state-of-software-quality/api/ • https://boomi.com/content/report/api-economy-2024/ • https://content.salt.security/state-api-report.html
41. Thank You! Any Questions? Connect: @frank-kilcommins @fkilcommins frank.kilcommins@smartbear.com