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

Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies
December 6, 7 & 8, 2023

Managing OpenAPI Documents at Scale
Stéve Sfartz, Principal Architect, API 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 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
22. Thank You!