Tweet
Tweet

Slide 1

Slide 1 text

PATTERNS FOR AUTOMATING API PRODUCT DELIVERY By Ikenna Nwaiwu 10th April 2024

Slide 2

Slide 2 text

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!)

Slide 3

Slide 3 text

Goal of this talk • Show how to use four control patterns to reduce risk and improve the value of your API.

Slide 4

Slide 4 text

Participate • Content and code example repo https://github.com/IkennaConsulting/patterns-for-api- delivery • Join at Slido.com #1443618

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Intro to the Pattern Format

Slide 7

Slide 7 text

Why these control patterns? At a high level, API development processes face common problems that have common solutions.

Slide 8

Slide 8 text

Why these control patterns? Help improve the developer experience of your API Help improve your operational efficiency

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Pattern 1: API Consistency Controls (Linting)

Slide 11

Slide 11 text

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.

Slide 12

Slide 12 text

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.

Slide 13

Slide 13 text

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.

Slide 14

Slide 14 text

Countermeasures Use API linting tools to enforce API style guides and standards. Integrate the API linting tool with your CI/CD pipeline.

Slide 15

Slide 15 text

Automated governance framework

Slide 16

Slide 16 text

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.

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Contraindications • The early part of product development • Non-important API

Slide 20

Slide 20 text

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.)

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

Alternatives Manual API design reviews and checklists

Slide 23

Slide 23 text

Pattern 2: Automated Breaking Change Controls

Slide 24

Slide 24 text

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.

Slide 25

Slide 25 text

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..."

Slide 26

Slide 26 text

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.

Slide 27

Slide 27 text

Automated governance framework

Slide 28

Slide 28 text

Benefits Better API adoption Reduce customer attrition Reduced support and rework costs Lower cognitive load for producers and consumers

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

Challenges with applying this pattern The absence of a provider’s breaking change policy relegates the decision to the tool used. Handling deprecations

Slide 32

Slide 32 text

Contraindications • New product development - early part of product life cycle

Slide 33

Slide 33 text

Alternatives Manually detect changes in API design reviews For internal APIs - consumer-driven contract testing

Slide 34

Slide 34 text

Pattern 3: API Conformance Controls - Conformance tests

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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)

Slide 38

Slide 38 text

Automated governance framework

Slide 39

Slide 39 text

Benefits Reliable, trustworthy documentation Better developer experience More correct SDKs and other generated artefacts Lower support costs from defects

Slide 40

Slide 40 text

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.

Slide 41

Slide 41 text

Code example Pb33f Wiretap Schemathesis https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/conformance-checks.yaml

Slide 42

Slide 42 text

Challenges • Conformance testing is expensive to run end-to-end as part of regular test suite for a public API.

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

Contraindications Code-first development Good server stub code generation minimises the need for conformance tests

Slide 45

Slide 45 text

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)

Slide 46

Slide 46 text

Pattern 4: Code Generation Controls

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

Countermeasures • Use a code generation library to generate API client and server-stub code from your API definition

Slide 49

Slide 49 text

Benefits Lower cognitive load for API consumers 'SDK first experience' Save development time for API consumers and API producers Reduce API definition drift

Slide 50

Slide 50 text

Code example Fern Microsoft Kiota OpenAPI Generator https://github.com/IkennaConsulting/patterns-for-api- delivery/blob/main/.github/workflows/code-generation.yaml

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

Tips • Consider using SDK code generation as a service like Speakeasy and Apimatic

Slide 53

Slide 53 text

Contraindications • No budget / resources to support client SDKs

Slide 54

Slide 54 text

Alternatives Client hand- coded integration Provider hand- coded client SDKs Provider hand- coded server stubs

Slide 55

Slide 55 text

Conclusion

Slide 56

Slide 56 text

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.

Slide 57

Slide 57 text

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