apidays Paris 2022 - The 12 Facets of the OpenAPI Specification, Steve Sfartz, Cisco

apidays Paris 2022 - APIs the next 10 years: Software, Society, Sovereignty, Sustainability
December 14, 15 & 16, 2022

The 12 Facets of the OpenAPI Specification
Steve Sfartz, Principal Architect 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/

Deep dive into the API industry with our reports:
https://www.apidays.global/industry-reports/

Subscribe to our global newsletter:
https://apidays.typeform.com/to/i1MPEW

Transcript

1. APIs the next 10 years: Software, Society, Sovereignty, Sustainability December 14, 15 & 16, 2022 Stève Sfartz Principal Architect, Cisco
2. Stève Sfartz, Principal Architect – Cisco Dec 14th, 2022 the 12 facets of OpenAPI
3. 2023 SERIES OF EVENT New York May 16&17 Australia October 11&12 Singapore April 12&13 Helsinki & North June 5&6 Paris SEPTEMBER London November 15&16 June 28-30 SILICON VALLEY March 14&15 Dubai & Middle East February 22&23
4. © 2022 Cisco and/or its affiliates. #apidays /Cisco/DevNet/StèveSfartz • API Architect in Cisco Developer Relations • Technical Lead for API Experience and Cisco API Guidelines: prescriptive standards and best practices for API & SDKs • Working to deliver 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
5. #1. OpenAPI to describe API Contracts
6. © 2022 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 as a result • OpenAPI Specification (OAS) is a standard to define contracts for Web API • Example of OAS document 5
7. #2. Authoring OAS Documents
8. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Editing with SwaggerEditor https://editor.swagger.io/ 7
9. #3. Publish Reference Documentation
10. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays API Reference Documentation developer.cisco.com/meraki/api-v1/#!create-organization • Automatically rendered from OAS documents 9
11. #4. Try out API Operations
12. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 11
13. #5. Generate Code
14. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Auto-generate client code • From the documentation itself • From a CLI tool, create client and server code. import requests url="https://api.meraki.com/api/v1/organizations" payload=None headers={ "Content-Type": "application/json", "Accept": "application/json", "X-Cisco-Meraki-API-Key": "6bec40c…9ea0" } response=requests.request('GET', url, headers=headers, data = payload) print(response.text.encode('utf8')) python 13
15. #6. Mock APIs
16. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 15 Mocking APIs
17. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Summary OpenAPI to #1. Describe API contracts #2. Author OAS documents #3. Publish documentation #4. Try out an API #5. Generate Code #6. Mock an API 16
18. #7. The OpenAPI Specification
19. © 2022 Cisco and/or its affiliates. All rights reserved #apidays The OpenAPI Initiative Charter https://www.openapis.org/ 18
20. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 19 Versions of the OpenAPI Specifications full compatibility with modern JSON Schema [Draft 2020-12] OpenAPI 2.0 - 2014 OpenAPI 3.0 - 2017 OpenAPI 3.1 - 2021
21. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays OAS v3.0 as the default import format https://www.apimatic.io/blog/2022/03/top-api-specification-trends-2019-2022/ “Since August 2019, the number of imported OAS v3.0 documents has surpassed OAS v2.0” APIMatic March 2022 20
22. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays but… OAS v2.0 still largely spread API Specification Transformation Trends 21 “50% users preferred to convert to OpenAPI v2.0 overs 3.0” APIMatic March 2022 • quality of support for OpenAPI v3.0 in tools • legacy tools that still supports v2.0 only.
23. #8. Terminology
24. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays API Definition OpenAPI Specification (OAS) OAS document The OpenAPI Specification is a programming language-agnostic standard used to describe the contract for HTTP/REST APIs An OAS document contains the description of the full set or a subset of the API features. OAS document should be read as: “a document that conforms to the OpenAPI Specification” OAS document OAS Document Terminology An API Definition describes the full contract for an API. In the case of HTTP/REST APIs, the API Definition consists in a set of OAS documents. Often, one OAS document will be sufficient to fully define the API. 23
25. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Terminology • OpenAPI Specification, OpenAPI Initiative, OpenAPI Tools, OpenAPI • OAS Document: describe an API using the OpenAPI Specification • API Contract, API Definition, API Specification/Spec, API Description • API Documentation: the reference documentation for an API, published on a web site, and kept in sync with a version of an API • API Endpoint, API: the URL at which an API version can be accessed, such as ‘https://api.meraki.com/v1/’ • API Path, REST Resource, API: a URL such as ‘/organizations’ • API Operation, API: a Path + a method such as ‘GET /organizations’ • SDK, Client Library, API: ready-to-use code to consume an API 24
26. © 2022 Cisco and/or its affiliates. #apidays API Guidelines • An API is a network programmatic interface that a product - may be bare metal hardware, or virtual machine or software – AND - may be cloud or on- premises – publishes. • It has versions – it’s the API lifecycle • For every update, an API would publish its contract as one or multiple OAS documents for download or online browsing. • Every API version provides a documentation which includes authentication instructions, developer guides, code samples and reference documentation… and an API changelog. 25
27. #9. OAS Documents Management & Lifecycle
28. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays OAS Document Lifecycle Product Manager OAS Document draft 1 Engineering Lead Tech Writer 1. Create initial OAS document 2. Expand OAS document with payload and errors 3. Enrich OAS documents with descriptions and examples developer.cisco.com OAS Document draft 2 OAS Document draft … 4. Integrate with API documentation publishing tool 27
29. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays OAS Documents Workflow Best Practices Single Source of Truth Define where the OAS documents of your API will be stored • Single source of truth • OAS documents should be checked into a git repo to track changes Clarify Strategy Define who is responsible to merge changes • Whether a product manager, technical writer or technical lead – be consistent • Use GitHub pull requests for tracking and merging changes Educate the Team Educate your team members on OAS • OAS fundamentals • OAS workflow • OAS toolsets (linters, code generators...) Refine the Process Practice and refine as needed • Update OAS documents, review PR and merge changes • Maintain an API Changelog • This workflow may take time to establish 28
30. #10. Accurate OAS Documents
31. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Code as the source of truth Convert code comments or annotations 30 paths: "/pets/{category}": post: description: List all pets in a category parameters: - in: path name: category required: true description: Pet category schema: type: string default: all - in: query name: limit description: Amt returned schema: type: integer format: int32 responses: '200': description: Successful response requestBody: content: application/json: schema: type: object properties: search: type: string description: Search pet details strict: type: boolean description: Exact matches? https://openap.is/
32. #11. Automate Design Reviews
33. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays OAS Documents Static Analysis Detecting Quality or Security Faults 32
34. #12. Detecting Drifts and Zombies
35. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Drifts & Zombies Comparing OAS documents with live traffic observations 34
36. #13. API Changelogs
37. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays API Changelog • one operation added • one breaking change detected
38. #14. API Lifecycle and Compliance Management
39. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Highly Reliable (Lifecycle with deprecation notices, complete & accurate definition, complete changelog) API Contract Health Unreliable (Breaking changes, no or partial changelog, typically unstructured or UI-led design) Evolving (Product-tied versions, changelogs and contract may not be complete, ie typically UI-led design) Versioned (API-specific lifecycle, definition published with large coverage, complete changelog) Trust API Contract Roadmap <18m feb22 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 38
40. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 39 API Lifecycle, Quality and Compliance https://developer.cisco.com/api-insights/
41. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 40
42. #15. OpenAPI Tools and Communities
43. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays openapi.tools/ 42
44. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays 43 OpenAPI Communities stoplight.io/api-roadmap-ebook techblog.cisco.com
45. Wrapup
46. © 2022 Cisco and/or its affiliates. All rights reserved. #apidays Who you are Benefits 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 45 blogs.cisco.com/developer/worldclassapis01
47. Lorem Ipsum cs.co/insight
48. Enter to win! http://cs.co/apidays Answer a few questions and enter to win Festavia string lights!
49. Develop: Secure It, Cloud It, Code It Apply to be a speaker today! cs.co/apispeakers
50. Thank You!