SlideShare a Scribd company logo
1 of 22
Download to read offline
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
Stève Sfartz, Principal Architect - Cisco December 8th, 2023
Managing
OpenAPI documents
at scale
© 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
© 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
© 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Agenda
▪ Vertical Scalability
▪ Horizontal Scalability
▪ Breaking changes
5
© 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
© 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
© 2023 Cisco and/or its affiliates. All rights reserved.
#apidays
Challenges
▪ Authoring documents
▪ Reviewing changes
Vertical Scalability
8
© 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
© 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
© 2023 Cisco and/or its affiliates.
#apidays
Horizontal Scalability
• How many APIs? Engineering Groups?
• 6 organizations, 9 domains, 100+ groups, 1,000+ APIs
11
© 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
© 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
© 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….
© 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
© 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
© 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
© 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
© 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​
© 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
© 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
Thank You!

More Related Content

Similar to Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco

Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
HostedbyConfluent
 

Similar to Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco (20)

apidays Paris 2022 - Adding a mock as a service capability to your API strate...
apidays Paris 2022 - Adding a mock as a service capability to your API strate...apidays Paris 2022 - Adding a mock as a service capability to your API strate...
apidays Paris 2022 - Adding a mock as a service capability to your API strate...
 
Apidays Paris 2023 - OpenAPI 3.1 and Spring-Boot 3 - What's New?, Badr Nass L...
Apidays Paris 2023 - OpenAPI 3.1 and Spring-Boot 3 - What's New?, Badr Nass L...Apidays Paris 2023 - OpenAPI 3.1 and Spring-Boot 3 - What's New?, Badr Nass L...
Apidays Paris 2023 - OpenAPI 3.1 and Spring-Boot 3 - What's New?, Badr Nass L...
 
WAN Automation Engine API Deep Dive
WAN Automation Engine API Deep DiveWAN Automation Engine API Deep Dive
WAN Automation Engine API Deep Dive
 
Why Automate the Network?
Why Automate the Network?Why Automate the Network?
Why Automate the Network?
 
Applying Hyper-scale Design Patterns to Routing
Applying Hyper-scale Design Patterns to RoutingApplying Hyper-scale Design Patterns to Routing
Applying Hyper-scale Design Patterns to Routing
 
Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
Apicurio Registry: Event-driven APIs & Schema governance for Apache Kafka | F...
 
Automating a World-Class Technology Conference; Behind the Scenes of CiscoLive
Automating a World-Class Technology Conference; Behind the Scenes of CiscoLiveAutomating a World-Class Technology Conference; Behind the Scenes of CiscoLive
Automating a World-Class Technology Conference; Behind the Scenes of CiscoLive
 
Presentation at the 2016 Linux Foundation Collab Summit
Presentation at the 2016 Linux Foundation Collab SummitPresentation at the 2016 Linux Foundation Collab Summit
Presentation at the 2016 Linux Foundation Collab Summit
 
Deploy and Access WebSphere Liberty and StrongLoop REST Endpoints on IBM Bluemix
Deploy and Access WebSphere Liberty and StrongLoop REST Endpoints on IBM BluemixDeploy and Access WebSphere Liberty and StrongLoop REST Endpoints on IBM Bluemix
Deploy and Access WebSphere Liberty and StrongLoop REST Endpoints on IBM Bluemix
 
Zure Azure PaaS Zero to Hero - DevOps training day
Zure Azure PaaS Zero to Hero - DevOps training dayZure Azure PaaS Zero to Hero - DevOps training day
Zure Azure PaaS Zero to Hero - DevOps training day
 
DevOps Spain 2019. Pedro Mendoza-AWS
DevOps Spain 2019. Pedro Mendoza-AWSDevOps Spain 2019. Pedro Mendoza-AWS
DevOps Spain 2019. Pedro Mendoza-AWS
 
Migrating from IBM API Connect v5 to v2018
Migrating from IBM API Connect v5 to v2018Migrating from IBM API Connect v5 to v2018
Migrating from IBM API Connect v5 to v2018
 
Extend soa with api management Sangam18
Extend soa with api management Sangam18Extend soa with api management Sangam18
Extend soa with api management Sangam18
 
Drupal 8 and 9, Backwards Compatibility, and Drupal 8.5 update
Drupal 8 and 9, Backwards Compatibility, and Drupal 8.5 updateDrupal 8 and 9, Backwards Compatibility, and Drupal 8.5 update
Drupal 8 and 9, Backwards Compatibility, and Drupal 8.5 update
 
BEST REST in OpenStack
BEST REST in OpenStackBEST REST in OpenStack
BEST REST in OpenStack
 
DevOps for Databricks
DevOps for DatabricksDevOps for Databricks
DevOps for Databricks
 
Cisco APIC AAG
Cisco APIC AAGCisco APIC AAG
Cisco APIC AAG
 
TFI2014 Session II - Requirements for SDN - Brian Field
TFI2014 Session II - Requirements for SDN - Brian FieldTFI2014 Session II - Requirements for SDN - Brian Field
TFI2014 Session II - Requirements for SDN - Brian Field
 
Elastic-Engineering
Elastic-EngineeringElastic-Engineering
Elastic-Engineering
 
IBM Z for the Digital Enterprise 2018 - Offering API channel to application a...
IBM Z for the Digital Enterprise 2018 - Offering API channel to application a...IBM Z for the Digital Enterprise 2018 - Offering API channel to application a...
IBM Z for the Digital Enterprise 2018 - Offering API channel to application a...
 

More from apidays

More from apidays (20)

Apidays New York 2024 - Scaling API-first by Ian Reasor and Radu Cotescu, Adobe
Apidays New York 2024 - Scaling API-first by Ian Reasor and Radu Cotescu, AdobeApidays New York 2024 - Scaling API-first by Ian Reasor and Radu Cotescu, Adobe
Apidays New York 2024 - Scaling API-first by Ian Reasor and Radu Cotescu, Adobe
 
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
 
Apidays New York 2024 - The value of a flexible API Management solution for O...
Apidays New York 2024 - The value of a flexible API Management solution for O...Apidays New York 2024 - The value of a flexible API Management solution for O...
Apidays New York 2024 - The value of a flexible API Management solution for O...
 
Apidays New York 2024 - The secrets to Graph success, by Leah Hurwich Adler, ...
Apidays New York 2024 - The secrets to Graph success, by Leah Hurwich Adler, ...Apidays New York 2024 - The secrets to Graph success, by Leah Hurwich Adler, ...
Apidays New York 2024 - The secrets to Graph success, by Leah Hurwich Adler, ...
 
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
 
Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
 
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
 
Apidays New York 2024 - API Discovery - From Crawl to Run by Rob Dickinson, G...
Apidays New York 2024 - API Discovery - From Crawl to Run by Rob Dickinson, G...Apidays New York 2024 - API Discovery - From Crawl to Run by Rob Dickinson, G...
Apidays New York 2024 - API Discovery - From Crawl to Run by Rob Dickinson, G...
 
Apidays Singapore 2024 - Building with the Planet in Mind by Sandeep Joshi, M...
Apidays Singapore 2024 - Building with the Planet in Mind by Sandeep Joshi, M...Apidays Singapore 2024 - Building with the Planet in Mind by Sandeep Joshi, M...
Apidays Singapore 2024 - Building with the Planet in Mind by Sandeep Joshi, M...
 
Apidays Singapore 2024 - Connecting Cross Border Commerce with Payments by Gu...
Apidays Singapore 2024 - Connecting Cross Border Commerce with Payments by Gu...Apidays Singapore 2024 - Connecting Cross Border Commerce with Payments by Gu...
Apidays Singapore 2024 - Connecting Cross Border Commerce with Payments by Gu...
 
Apidays Singapore 2024 - Privacy Enhancing Technologies for AI by Mark Choo, ...
Apidays Singapore 2024 - Privacy Enhancing Technologies for AI by Mark Choo, ...Apidays Singapore 2024 - Privacy Enhancing Technologies for AI by Mark Choo, ...
Apidays Singapore 2024 - Privacy Enhancing Technologies for AI by Mark Choo, ...
 
Apidays Singapore 2024 - Blending AI and IoT for Smarter Health by Matthew Ch...
Apidays Singapore 2024 - Blending AI and IoT for Smarter Health by Matthew Ch...Apidays Singapore 2024 - Blending AI and IoT for Smarter Health by Matthew Ch...
Apidays Singapore 2024 - Blending AI and IoT for Smarter Health by Matthew Ch...
 
Apidays Singapore 2024 - OpenTelemetry for API Monitoring by Danielle Kayumbi...
Apidays Singapore 2024 - OpenTelemetry for API Monitoring by Danielle Kayumbi...Apidays Singapore 2024 - OpenTelemetry for API Monitoring by Danielle Kayumbi...
Apidays Singapore 2024 - OpenTelemetry for API Monitoring by Danielle Kayumbi...
 
Apidays Singapore 2024 - Connecting Product and Engineering Teams with Testin...
Apidays Singapore 2024 - Connecting Product and Engineering Teams with Testin...Apidays Singapore 2024 - Connecting Product and Engineering Teams with Testin...
Apidays Singapore 2024 - Connecting Product and Engineering Teams with Testin...
 
Apidays Singapore 2024 - The Growing Carbon Footprint of Digitalization and H...
Apidays Singapore 2024 - The Growing Carbon Footprint of Digitalization and H...Apidays Singapore 2024 - The Growing Carbon Footprint of Digitalization and H...
Apidays Singapore 2024 - The Growing Carbon Footprint of Digitalization and H...
 
Apidays Singapore 2024 - Building Digital Trust in a Digital Economy by Veron...
Apidays Singapore 2024 - Building Digital Trust in a Digital Economy by Veron...Apidays Singapore 2024 - Building Digital Trust in a Digital Economy by Veron...
Apidays Singapore 2024 - Building Digital Trust in a Digital Economy by Veron...
 
Apidays Singapore 2024 - API Monitoring x SRE by Ryan Ashneil and Eugene Wong...
Apidays Singapore 2024 - API Monitoring x SRE by Ryan Ashneil and Eugene Wong...Apidays Singapore 2024 - API Monitoring x SRE by Ryan Ashneil and Eugene Wong...
Apidays Singapore 2024 - API Monitoring x SRE by Ryan Ashneil and Eugene Wong...
 
Apidays Singapore 2024 - A nuanced approach on AI costs and benefits for the ...
Apidays Singapore 2024 - A nuanced approach on AI costs and benefits for the ...Apidays Singapore 2024 - A nuanced approach on AI costs and benefits for the ...
Apidays Singapore 2024 - A nuanced approach on AI costs and benefits for the ...
 
Apidays Singapore 2024 - Modernizing Securities Finance by Madhu Subbu
Apidays Singapore 2024 - Modernizing Securities Finance by Madhu SubbuApidays Singapore 2024 - Modernizing Securities Finance by Madhu Subbu
Apidays Singapore 2024 - Modernizing Securities Finance by Madhu Subbu
 
Apidays Singapore 2024 - How APIs drive business at BNP Paribas by Quy-Doan D...
Apidays Singapore 2024 - How APIs drive business at BNP Paribas by Quy-Doan D...Apidays Singapore 2024 - How APIs drive business at BNP Paribas by Quy-Doan D...
Apidays Singapore 2024 - How APIs drive business at BNP Paribas by Quy-Doan D...
 

Recently uploaded

Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
Obat Aborsi 088980685493 Jual Obat Aborsi
 
Simplify hybrid data integration at an enterprise scale. Integrate all your d...
Simplify hybrid data integration at an enterprise scale. Integrate all your d...Simplify hybrid data integration at an enterprise scale. Integrate all your d...
Simplify hybrid data integration at an enterprise scale. Integrate all your d...
varanasisatyanvesh
 
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
zifhagzkk
 
Displacement, Velocity, Acceleration, and Second Derivatives
Displacement, Velocity, Acceleration, and Second DerivativesDisplacement, Velocity, Acceleration, and Second Derivatives
Displacement, Velocity, Acceleration, and Second Derivatives
23050636
 
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
wsppdmt
 
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di Bontang
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di  Bontangobat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di  Bontang
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di Bontang
siskavia95
 
bams-3rd-case-presentation-scabies-12-05-2020.pptx
bams-3rd-case-presentation-scabies-12-05-2020.pptxbams-3rd-case-presentation-scabies-12-05-2020.pptx
bams-3rd-case-presentation-scabies-12-05-2020.pptx
JocylDuran
 
Audience Researchndfhcvnfgvgbhujhgfv.pptx
Audience Researchndfhcvnfgvgbhujhgfv.pptxAudience Researchndfhcvnfgvgbhujhgfv.pptx
Audience Researchndfhcvnfgvgbhujhgfv.pptx
Stephen266013
 
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotecAbortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
Abortion pills in Riyadh +966572737505 get cytotec
 
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
wsppdmt
 

Recently uploaded (20)

Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
Jual Obat Aborsi Lhokseumawe ( Asli No.1 ) 088980685493 Obat Penggugur Kandun...
 
Simplify hybrid data integration at an enterprise scale. Integrate all your d...
Simplify hybrid data integration at an enterprise scale. Integrate all your d...Simplify hybrid data integration at an enterprise scale. Integrate all your d...
Simplify hybrid data integration at an enterprise scale. Integrate all your d...
 
Seven tools of quality control.slideshare
Seven tools of quality control.slideshareSeven tools of quality control.slideshare
Seven tools of quality control.slideshare
 
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
如何办理(Dalhousie毕业证书)达尔豪斯大学毕业证成绩单留信学历认证
 
Displacement, Velocity, Acceleration, and Second Derivatives
Displacement, Velocity, Acceleration, and Second DerivativesDisplacement, Velocity, Acceleration, and Second Derivatives
Displacement, Velocity, Acceleration, and Second Derivatives
 
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
一比一原版(UCD毕业证书)加州大学戴维斯分校毕业证成绩单原件一模一样
 
SAC 25 Final National, Regional & Local Angel Group Investing Insights 2024 0...
SAC 25 Final National, Regional & Local Angel Group Investing Insights 2024 0...SAC 25 Final National, Regional & Local Angel Group Investing Insights 2024 0...
SAC 25 Final National, Regional & Local Angel Group Investing Insights 2024 0...
 
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di Bontang
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di  Bontangobat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di  Bontang
obat aborsi Bontang wa 082135199655 jual obat aborsi cytotec asli di Bontang
 
RESEARCH-FINAL-DEFENSE-PPT-TEMPLATE.pptx
RESEARCH-FINAL-DEFENSE-PPT-TEMPLATE.pptxRESEARCH-FINAL-DEFENSE-PPT-TEMPLATE.pptx
RESEARCH-FINAL-DEFENSE-PPT-TEMPLATE.pptx
 
bams-3rd-case-presentation-scabies-12-05-2020.pptx
bams-3rd-case-presentation-scabies-12-05-2020.pptxbams-3rd-case-presentation-scabies-12-05-2020.pptx
bams-3rd-case-presentation-scabies-12-05-2020.pptx
 
Solution manual for managerial accounting 8th edition by john wild ken shaw b...
Solution manual for managerial accounting 8th edition by john wild ken shaw b...Solution manual for managerial accounting 8th edition by john wild ken shaw b...
Solution manual for managerial accounting 8th edition by john wild ken shaw b...
 
Rolex Watch - Design Decision Analysis.
Rolex Watch -  Design Decision Analysis.Rolex Watch -  Design Decision Analysis.
Rolex Watch - Design Decision Analysis.
 
Chapter 1 - Introduction to Data Mining Concepts and Techniques.pptx
Chapter 1 - Introduction to Data Mining Concepts and Techniques.pptxChapter 1 - Introduction to Data Mining Concepts and Techniques.pptx
Chapter 1 - Introduction to Data Mining Concepts and Techniques.pptx
 
Aggregations - The Elasticsearch "GROUP BY"
Aggregations - The Elasticsearch "GROUP BY"Aggregations - The Elasticsearch "GROUP BY"
Aggregations - The Elasticsearch "GROUP BY"
 
What is Insertion Sort. Its basic information
What is Insertion Sort. Its basic informationWhat is Insertion Sort. Its basic information
What is Insertion Sort. Its basic information
 
Audience Researchndfhcvnfgvgbhujhgfv.pptx
Audience Researchndfhcvnfgvgbhujhgfv.pptxAudience Researchndfhcvnfgvgbhujhgfv.pptx
Audience Researchndfhcvnfgvgbhujhgfv.pptx
 
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotecAbortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
Abortion pills in Riyadh Saudi Arabia (+966572737505 buy cytotec
 
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
如何办理澳洲拉筹伯大学毕业证(LaTrobe毕业证书)成绩单原件一模一样
 
Jual Obat Aborsi Bandung (Asli No.1) Wa 082134680322 Klinik Obat Penggugur Ka...
Jual Obat Aborsi Bandung (Asli No.1) Wa 082134680322 Klinik Obat Penggugur Ka...Jual Obat Aborsi Bandung (Asli No.1) Wa 082134680322 Klinik Obat Penggugur Ka...
Jual Obat Aborsi Bandung (Asli No.1) Wa 082134680322 Klinik Obat Penggugur Ka...
 
Case Study 4 Where the cry of rebellion happen?
Case Study 4 Where the cry of rebellion happen?Case Study 4 Where the cry of rebellion happen?
Case Study 4 Where the cry of rebellion happen?
 

Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco

  • 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 8th, 2023 Managing OpenAPI documents at scale
  • 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