The document outlines four control patterns for automating API product delivery, aimed at reducing risks and enhancing the value of APIs. It covers API consistency controls, breaking change controls, API conformance tests, and code generation controls, detailing their benefits, challenges, and best practices. The author encourages experimentation with various tools within these patterns to streamline API development processes.

1. PATTERNS FOR AUTOMATING
API PRODUCT DELIVERY
By Ikenna Nwaiwu

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