Patterns for Automating API Product Delivery

Automating API product delivery is about automating workflows to improve the quality and delivery speed for APIs by applying APIOps principles. In this talk, I discuss patterns for:
> API consistency checks: Enforcing API design standards with linting tools like Spectral, Redocly CLI and Vacuum.
> API breaking change checks: Automating breaking-change checks with OpenAPI diff tools like Oasdiff
> API conformance checks: Ensuring accuracy of your API reference documents using API conformance tools like Schemathesis.
> API code generation: Generate server and client code using SDK generators like OpenAPI Generator

Transcript

1. PATTERNS FOR AUTOMATING API PRODUCT DELIVERY By Ikenna Nwaiwu 10th April 2024
2. About me • API Consultant @ Ikenna Consulting • We help organisations increase the value of their APIs and lower the cost of API delivery. • Author, Automating API Delivery (Manning, 2023) • Let’s connect https://www.linkedin.com/in/ikenna (if at the conference, get free book code!)
3. Goal of this talk • Show how to use four control patterns to reduce risk and improve the value of your API.
4. Participate • Content and code example repo https://github.com/IkennaConsulting/patterns-for-api- delivery • Join at Slido.com #1443618
5. Agenda Intro to the Pattern Format 1 – API Consistency Controls (API linting) 2 – Breaking Change Controls 3 – API Conformance Controls 4 – Code Generation Controls Conclusion
6. Intro to the Pattern Format
7. Why these control patterns? At a high level, API development processes face common problems that have common solutions.
8. Why these control patterns? Help improve the developer experience of your API Help improve your operational efficiency
9. The pattern format I'll use for each pattern Problem/Why? Countermeasure How it fits in the automated governance framework Benefits Code example Challenges Contraindications (when not to use it) Tips + What to look out for when choosing a tool Alternative patterns/practices
10. Pattern 1: API Consistency Controls (Linting)
11. The problem When multiple teams in an org build APIs, standardisation and inconsistency problems arise. 51% of the respondents to the 2023 Smartbear State of Software Quality | API report sited standardisation as the biggest challenge in API development.
12. The problem There is no time to read, remember and apply all the details of your API style guides. 43% of the respondents of the Postman State of API 2023 report sited lack of time as the biggest obstacle to producing APIs.
13. The problem Teams applying DevOps face a high cognitive load. The 3rd highest obstacle to producing APIs in the Postman survey is the lack of API design skills.
14. Countermeasures Use API linting tools to enforce API style guides and standards. Integrate the API linting tool with your CI/CD pipeline.
15. Automated governance framework
16. Benefits Improved API consistency and developer experience for the API consumer. Improved lead time in API design. Improved API security at the design stage. Reduce time, toil and mental effort spent on design debates and API reviews.
17. Code example Redocly CLI Optic Vacuum Spectral AI-assisted linting with Anthropic Specialist artefact linters https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/api-consistency.yml
18. Challenges with applying this pattern No style guide on which to base the linting rules API definitions not in version control Writing rules takes effort No API platform/governance team to support the rules
19. Contraindications • The early part of product development • Non-important API
20. Tips. When picking a linting tool, consider: Speed! Good error messages Ease of writing rules Extra features of CLIs: managing API definition files (bundling, splitting, joining, etc.)
21. Tips Do start linting even if you don't have a style guide Lint in the pipeline. Provide docs & tools for linting locally (editor, CLI) for fast feedback. You may need more than one kind of linter
22. Alternatives Manual API design reviews and checklists
23. Pattern 2: Automated Breaking Change Controls
24. The Problem Breaking change: A change to an API that requires existing client integration code to change. Breaking changes can come from: A change in the API definition. A change in the code or API config not reflected in the definition.
25. The Problem Real customer quote 1: "You should stop doing breaking changes to the API ASAP. If you do not, as a business, you will lose a massive amount of customers and lose reputation.” Real customer quote 2: "The way [company] handles API changes is going to impact our business since we consume the data in production. We are left without any solutions or guidelines. We found out a bit late about the breaking change that is going to happen tomorrow..."
26. Countermeasures Have a clear API versioning strategy that minimises disruption to existing client integrations. Use breaking change detection tools. Give visibility of changes with a comprehensive API change log.
27. Automated governance framework
28. Benefits Better API adoption Reduce customer attrition Reduced support and rework costs Lower cognitive load for producers and consumers
29. Code example Tufin/Oasdiff UseOptic/Optic Pb33f OpenAPI-Changes Bump.sh https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/breaking-checks.yaml
30. Tips Have well-defined breaking change rules. https://github.com/Tufin/oasdiff/blob/ main/BREAKING-CHANGES- EXAMPLES.md Generate and publish an API change log in a standard format. Example standard format https://keepachangelog.com/en/1.0.0
31. Challenges with applying this pattern The absence of a provider’s breaking change policy relegates the decision to the tool used. Handling deprecations
32. Contraindications • New product development - early part of product life cycle
33. Alternatives Manually detect changes in API design reviews For internal APIs - consumer-driven contract testing
34. Pattern 3: API Conformance Controls - Conformance tests
35. The Problem The API reference can become inconsistent with the actual API implementation. 52% of the respondents to the 2023 Smartbear State of Software Quality | API report cited documentation being out of sync as the 2nd largest hindrance to API documentation
36. The Problem "It ain’t what you don't know that gets you into trouble. It's what you know for sure that just ain't so." – Mark Twain
37. Countermeasure Run conformance (also called contract tests) to ensure public API reference (especially the schema) is in sync with implementation. Better suited for public APIs, than for internal APIs whose evolution can be managed with consumer-based contract testing techniques (e.g Pact)
38. Automated governance framework
39. Benefits Reliable, trustworthy documentation Better developer experience More correct SDKs and other generated artefacts Lower support costs from defects
40. My typology of conformance tests Code-based end-to-end schema test. Code-based controller schema test. Fuzzer schema test: Auto- generated end-to-end schema test with a fuzzing tool. End-to-end schema testing with validating proxy.
41. Code example Pb33f Wiretap Schemathesis https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/conformance-checks.yaml
42. Challenges • Conformance testing is expensive to run end-to-end as part of regular test suite for a public API.
43. Tips Run on PR changes (lightweight) Minimise running large end-to-end conformance test suites (expensive) Multiple controls helpful - testing conformance + generating code from specs Aim to detect undocumented properties. Set additionalProperties:false before test runs using: https://github.com/NickHeap2/add-props-flipflop
44. Contraindications Code-first development Good server stub code generation minimises the need for conformance tests
45. Alternatives Generate code from specs (API design-first) Generate spec from code (code-first) Internal APIs - consumer-driven contract testing (but not for public / external APIs)
46. Pattern 4: Code Generation Controls
47. Problem OpenAPI definitions that cannot be used to generate SDKs 01 No SDKs – long time to first hello world. 02 Drift between API definition and server code. 03
48. Countermeasures • Use a code generation library to generate API client and server-stub code from your API definition
49. Benefits Lower cognitive load for API consumers 'SDK first experience' Save development time for API consumers and API producers Reduce API definition drift
50. Code example Fern Microsoft Kiota OpenAPI Generator https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/code-generation.yaml
51. Challenges • Poor quality API definitions • Maintenance overhead. If multiple SDKs, cost of • addressing specific issues for each SDK • deployment pipeline, documentation for each • Resource allocation • Release management • tracking SDK version and use by clients • testing SDKs to avoid breaking changes
52. Tips • Consider using SDK code generation as a service like Speakeasy and Apimatic
53. Contraindications • No budget / resources to support client SDKs
54. Alternatives Client hand- coded integration Provider hand- coded client SDKs Provider hand- coded server stubs
55. Conclusion
56. Conclusion If you are building lots of APIs, consider these four controls in your API delivery process: API consistency controls / linting, breaking change controls, API conformance controls and code generation controls. You may need to use more than one tool for each control. Experiment with the tools. The goal is to reduce risk and improve the value of your API.
57. Questions ? • Join at Slido.com #1443618 • Let’s connect https://www.linkedin.com/in/ikenna (if at the conference, get free book code!) • Content and code example repo https://github.com/IkennaConsulting/patterns-for-api-delivery