Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies December 6, 7 & 8, 2023 Why API Contracts Matter Stève Sfartz, Principal Architect - API Quality and Developer Experience at Cisco ------ 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/

1. Stève Sfartz
Principal Architect - API Quality
and Developer Experience
Cisco
Software and APIs for Smart, Sustainable
and Sovereign Societies
December 6, 7 & 8, 2023

2. Stève Sfartz, Principal Architect - Cisco December 6th, 2023
Why API Contracts
Matter

3. © 2023 Cisco and/or its affiliates.
#apidays
/Cisco/DevNet/StèveSfartz
• Principal Architect at Cisco Developer
Relations
• Lead for Cisco’s API Experience program
• Define internal standards that cover API
design, lifecycle and documentation
• Working towards a great and consistent
developer experience across Cisco
platforms
“vision
without
execution is
hallucination”
webex: stsfartz@cisco.com
github: ObjectIsAdvantag
twitter: @SteveSfartz
linkedin:/stevesfartz
3

4. © 2023 Cisco and/or its affiliates.
#apidays
APIs as Technical Contracts
• An application programming interface (API) specifies how software
components should interact with each other.
• As such, APIs are considered contracts between the organization
providing the API and developers consuming this API.
•
API Consumer API Provider
sends information in the specified format
"if you provide information in this format, I – the API - will perform a specific
action and return a result in this format".
responds with a result in the specified format
action

5. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Formalizing API Contracts
• For every operation supported by
an API, its contract describes:
• what must be provided as input
• what will happen
• and what, if any, data is returned
• OpenAPI Specification (OAS) is a
standard to define contracts for
HTTP/REST API
• Example of an OpenAPI document

6. © 2023 Cisco and/or its affiliates.
#apidays
API Definition
OpenAPI Specification
OAS document
The OpenAPI Specification is a standard used
to describe contracts for HTTP/REST APIs
An OpenAPI document contains the description
of the full set or a subset of the API features.
OAS document
OpenAPI Documents
API Contract: Definition and Lifecycle for an API
An API Definition describes all the operations
exposed by an API including
incoming/outgoing payloads.
6

7. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
API Lifecycle
API Definition
OpenAPI Specification
OAS document
The OpenAPI Specification is a standard used
to describe contracts for HTTP/REST APIs
An OpenAPI document contains the description
of the full set or a subset of the operations.
OAS document
OpenAPI Documents
API Contract: Definition and Lifecycle for an API
An API Definition describes all the operations
exposed including requests, responses and
errors.
v1 v2
1.1 1.2
Backward Compatibility
API Changelog
No breaking changes across minor versions
Deprecation policy
Major
minor
7

8. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
API Contract Quality
Unreliable
Breaking changes, no or partial changelog, typically UI-led design
Evolving
Product-led lifecycle, incomplete definition and changelog
Versioned
API-led lifecycle, complete definition and changelog
8
Trust
Highly Reliable
API-led lifecycle with published deprecation policy, automated changelog,
complete definition continuously checked against live traffic observations

9. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
API Contract Roadmap
API Contract
Roadmap
<18m
mar21
evolving versioned
API Contract Health
as the plan was
established
Timeline to
execute the
plan and
improve the
contract
Contract Health
after the plan will
be completed
9
Highly Reliable
Unreliable
Evolving
Versioned
Trust

10. March
2021
<18
months
Comments
Design Process
● ●
The design of the API is UI-led and without centralized governance. A heavy
investment on the design process is required. Moreover, the API does not follow
consistent conventions and includes multiple versions across paths.
API Definition
● ● An OpenAPI document exists. Getting to a 100% complete API Contracts is being
evaluated.
Changelog
● ●
A changelog is published for current and vNext versions of the API. BUT the
changelog is managed manually. Getting to a 100% accurate changelog will be
addressed by the engineering plan being evaluated.
Versioning
● ●
API versions tie to product versions. There were no plan at this stage to version the
API independently of the product. This will be fixed within the 18 months engineering
plan.
Deprecation
Policy ● ● The deprecation and EOL policy is not published as part of the API documentation.
Backward
Compatibility ● ● Some features are changed or deleted with the March 2021 version. No report of
breaking changes. Addressed by the engineering transformation plan in evaluation.
API Contract Health
<18m
<18m
<18m
<18m
API Contract Roadmap
< 18m
march21
evolving versioned
evaluating
<18m
<18m

11. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
OpenAPI Documents Static Analysis
Automated Detection of Design or Security Gaps
11
Change screenshot
> spectral lint --ruleset ruleset.yaml
openapi_document.yaml --format pretty -v

12. © 2023 Cisco and/or its affiliates.
#apidays
API Contract Completeness Linter
✓Well-formed OpenAPI document
✓Must contain meta information
✓Must describe one version only
✓Must have operation identifiers
✓Must have a success status code
✓Must have error status codes
✓Must have response schema defined
12

13. © 2023 Cisco and/or its affiliates.
#apidays
Spectral Rules for Contract Completeness
13
Spectral Rule Description
oas-schema
Malformed OpenAPI document, not adhering to the OpenAPI
specifications.
success-status-code
Some operations do not define a success status code. A successful
status code in the range 200, 201 or 204.
error-status-code At least one error status code must be defined in the 4xx or 5xx ranges
missing-schema-definition Some schema definitions are missing.
incomplete-schema-definition
Some schemas are partially defined. Every defined schema does not
use object as a final field when describing its object structure.
missing-returned-representation Some responses do not define a schema.

14. © 2023 Cisco and/or its affiliates.
#apidays
Spectral Rules for Contract Completeness
14
Rule Description
oas-meta-info
Some OpenAPI meta information is missing: info, title, version
basepath, license, securityDefinitions.
operationId-required Some operations do not include an operation identifier.
operationId-unique Some operation identifiers are not unique.
missing-version No version is specified in the server object of the OpenAPI Document.
single-versions Multiple versions detected.

15. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
The Lifecycle of OpenAPI Documents
Design-first
revision 1
Implement Document
1. Create
initial OpenAPI
document
2. Enrich with
parameters,
schemas and errors
3. Enrich with descriptions
and examples
developer.cisco.com
revision 2 more revisions
Versioned OpenAPI documents using semantic versioning
15
4. Integrate with
documentation publishing
toolchain

16. © 2023 Cisco and/or its affiliates.
#apidays
Now what if…
▪ … a new operation or updates to an existing operation did not
receive proper annotation
▪ Drift between the API contract and the actual API deployment
▪ Leading to
• Untested operation
• Incomplete API documentation
• Potential API security vulnerability
• Potential Personal Information
16

17. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Shadow: undocumented operation
17

18. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Shadow: undocumented query parameter
18

19. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Zombie: deprecated operation still active
19

20. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
API Security CI/CD Architecture
Open API
Static Analysis
3rd Party
API Scoring
API Fuzz Testing
API
Controller
API
Workload
CLI CLI
Deploy →
Release →
Test →
Build →
Code →
Code
Commit

21. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Highly Reliable
API-led lifecycle with published deprecation policy, automated changelog,
complete definition continuously checked against live traffic observations
Quality of API Contracts
Unreliable
Breaking changes, no or partial changelog, typically UI-led design
Evolving
Product-led lifecycle, incomplete definition and changelog
Versioned
API-led lifecycle, complete definition and changelog
21
Trust

22. © 2023 Cisco and/or its affiliates.
#apidays
Why API Contracts Matter
• Managing API Contracts involves pinpointing the specific
revisions of OpenAPI documents corresponding to API releases
deployed across various environments and continuously
comparing these with live traffic observations.
• What is the source of truth for your OpenAPI documents?
• Can you deduce timelines across revisions of OpenAPI
documents?
• To what extent are your CI/CD pipelines automated?
22

23. Thank You!