More Related Content Similar to Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco (20) Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco1. 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
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. All rights reserved.
#apidays
Value Proposition of the OpenAPI Specifications (OAS)
IT Pro or Application
Developer
consuming APIs
• OAS to discover the capabilities of an API
• OAS to automatically generate client code for your preferred language
• OAS as a pivot format to import/export API definitions across tools
Engineering group
publishing internal
or external-facing
APIs
• OAS to define the capabilities offered for your API
• OAS to publish low-level SDKs
• OAS to publish accurate and interactive documentation
• OAS to automate raw API Changelogs
• Authoring tools to initiate/edit OAS documents (Design-First)
• Source code annotations to generate OAS documents (Code-First)
• OAS linters to automate design reviews and adoption of REST Guidelines
• Static & dynamic analysis of API Security issues including OWASP Top 10
Security and
Compliance Officers
overseeing every
APIs
• OAS to maintain an inventory of an organization’s APIs
• Analysis of OAS documents to identify breaking changes and ensure
backward compatibility of existing API Contracts
• OAS to ensure compliance of new releases along CI/CD pipelines
• OAS to identify zombie & shadow operations via live traffic observations
4
5. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Agenda
▪ Vertical Scalability
▪ Horizontal Scalability
▪ Breaking changes
5
6. © 2023 Cisco and/or its affiliates.
#apidays
Vertical Scalability
How large OpenAPI documents can get?
▪ Petstore
▪ 13 paths,
▪ 19 operations
▪ 800 lines of YAML
6
7. © 2023 Cisco and/or its affiliates.
#apidays
Vertical Scalability
How large OpenAPI documents can get?
▪ Petstore: 13 paths, 19 operations, 800 lines of YAML
▪ Large (x100)
• 419 paths
• 661 operations
• 70,000 lines of YAML
▪ eXtra Large (x500)
• 2,000 paths
• 3,500 operations
• 420,000 lines of YAML
7
8. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Challenges
▪ Authoring documents
▪ Reviewing changes
Vertical Scalability
8
9. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Code as the source of truth
Convert code comments or annotations
BRKDEV-2249 9
Python Flask OpenAPI support
OpenAPI document
API reference documentation
10. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Challenges
▪ Authoring documents
▪ Reviewing changes
▪ Generating changelogs
▪ Rendering documentation
Vertical Scalability
10
OAS Utilities
▪ Generator
▪ Splitter
▪ Resolver with bundling strategy
▪ Sorting
▪ Filtering out
11. © 2023 Cisco and/or its affiliates.
#apidays
Horizontal Scalability
• How many APIs? Engineering Groups?
• 6 organizations, 9 domains, 100+ groups, 1,000+ APIs
11
12. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Challenges
▪ Continuously expanding number
of API programs
▪ Consistency in API design,
documentation and support
▪ Robust API lifecycles that offer
Backward Compatibility
Horizontal Scalability
12
Solutions
▪ Inventory
▪ Automation
▪ Compliance
13. © 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
13
4. Integrate with
documentation publishing
toolchain
14. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
OpenAPI Documents detailed workflow
Product Manager
OAS Document
First Draft
Engineering Lead Tech Writer
1. Create initial
OAS document
2. Expand OAS document
with payload and errors
4. Enrich with descriptions
and examples in a branch
OAS Document
Second Draft
OAS Document
Draft 2 (copy)
3. Integrate with API
documentation
publishing tool
Engineering git repo PubHub git repo
OAS Document
Third Draft
5. Push a PR to merge changes to
contribute changes
OAS Document
Draft X (merged)
6. Merge tech writers
changes to the reference
OAS document
more
drafts….
15. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
OpenAPI Documents Static Analysis
Automated Detection of Design or Security Gaps
15
Change screenshot
> spectral lint --ruleset ruleset.yaml
openapi_document.yaml --format pretty -v
16. © 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
API Quality & Security CI/CD Architecture
OpenAPI
Static Analysis
3rd Party
API Scoring
API Fuzz Testing
API
Controller
API
Workload
CLI CLI
Deploy →
Release →
Test →
Build →
Code →
Code
Commit
17. © 2023 Cisco and/or its affiliates.
#apidays
OpenAPI documents static analysis at scale
• Integrate with various CI/CD pipelines
• Protect confidentiality of engineering work and roadmaps
• Customizable to accommodate engineering group’s practices
• REST conventions
• Pull Request failure conditions (fail-below-scores, severity of findings:
error vs warning)
• Compliance process to enforce compliance in each organization
17
18. © 2023 Cisco and/or its affiliates.
#apidays
OpenAPI Documents Static Analysis at scale
• Integrate with various CI/CD pipelines
• Customizable to accommodate engineering group’s practices such
as REST conventions
• Facilitate compliance with requirements
• Protect confidentiality of engineering work and roadmaps
18
Company-wide compliance
Group-specific compliance
19. © 2023 Cisco and/or its affiliates.
#apidays
Backward Compatibility Principles
19
BwC.1
(recommended)
Provide a complete definition for the API (OpenAPI v2 or v3
document typically)
BwC.2
(required)
Generate a complete changelog for every API update
BwC.3
(required)
Identify breaking changes before an API gets release
BwC.4
(required)
Escalate internally in case of confirmed breaking change
identified
BwC.5
(required)
Version our API or deprecate a specific operation in case of
breaking change
BwC.6
(required)
Announce deprecations and breaking changes to the developer
community
20. © 2023 Cisco and/or its affiliates.
#apidays
Automating Backward Compatibility
• Prescriptive versioning and deprecation guidance for cloud and on-
premises APIs
• Backward Compatibility requirements to organize compliance
• Toolset to detect breaking changes along CI/CDs
• Analyzer to evaluate the completeness of an API Contract
• Target of 100% completeness for API Contracts for accurate changelogs
• Automated detection of non-backward compatible changes
20
21. © 2023 Cisco and/or its affiliates.
#apidays
Conclusion
• Managing OpenAPI documents at scale translates as
• Offering tools to facilitate the generation and rendering of reference
documentation from 100 to 100,000 lines of YAML
• Being in capacity to score OpenAPI documents and reject changes in an
automated way, with customizable criteria per engineering group
• Observing in production that your APIs behave as expected
• What is your OpenAPI toolset to author, render and manage compliance?
• Where do you store OpenAPI documents along the API lifecycle?
• How many OpenAPI analyzers do you need?
21