Apidays Paris 2023 - Why API Contracts Matter, Stève Sfartz, Cisco

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/

Transcript

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!