The 12 facets of the OpenAPI standard.pdf
0 likes69 views
The document presents an overview of the OpenAPI standard, detailing its utility in describing API contracts and facilitating various processes like authoring, documenting, and testing APIs. It emphasizes the importance of OpenAPI documents in ensuring clear communication between API providers and consumers, alongside offering insights into best practices for maintaining API lifecycles. Additionally, the document outlines the benefits for developers and compliance officers in utilizing OpenAPI for effective API management.
![© 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public
Versions of the OpenAPI Specifications
BRKDEV-2249
full compatibility
with modern
JSON Schema
[Draft 2020-12]
OpenAPI 2.0 - 2014 OpenAPI 3.0 - 2017 OpenAPI 3.1 - 2021
32](https://image.slidesharecdn.com/brkdev-2249-the12facetsoftheopenapistandard-230215125301-a58a2128/85/The-12-facets-of-the-OpenAPI-standard-pdf-32-320.jpg)
The 12 facets of the OpenAPI standard.pdf
- 1. Stève Sfartz, Principal Architect, Cisco Developer Relations BRKDEV-2249 The 12 facets of the OpenAPI standard
- 2. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public /Cisco/DevNet/StèveSfartz BRKDEV-2249 • Principal Architect in Cisco Developer Relations • Lead for the API Experience program • Define internal standards covering API documentation, design and lifecycle • Working for a great and consistent developer experience across Cisco platforms “vision without execution is hallucination” webex: stsfartz@cisco.com github: ObjectIsAdvantag twitter: @SteveSfartz 2
- 3. Enter your personal notes here Questions? Use Cisco Webex App to chat with the speaker after the session Find this session in the Cisco Live Mobile App Click “Join the Discussion” Install the Webex App or go directly to the Webex space Enter messages/questions in the Webex space How Webex spaces will be moderated until February 24, 2023. 1 2 3 4 © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Cisco Webex App 3 https://ciscolive.ciscoevents.com/ciscolivebot/#BRKDEV-2249 BRKDEV-2249
- 4. #1. OpenAPI to describe API Contracts
- 5. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 BRKDEV-2249 5
- 6. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Formalizing API Contracts • For every operation that an API supports, the contract describes: • what must be provided as input • what will happen • and what data is returned as a result • The OpenAPI specification is a standard to describe technical contracts for Web APIs • Example of OpenAPI document BRKDEV-2249 6
- 8. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Editing with SwaggerEditor https://editor.swagger.io/ BRKDEV-2249 8
- 9. Demo
- 11. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public API Reference Documentation developer.cisco.com/meraki/api-v1/#!create-organization • Automatically rendered from OpenAPI documents BRKDEV-2249 11
- 12. #4. Try out the API
- 13. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public BRKDEV-2249 13
- 15. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Auto-generate client code • From the reference documentation itself • Pick among the proposed languages 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 BRKDEV-2249 15
- 16. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Auto-generate client code • Using a CLI tool • For your preferred language 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 BRKDEV-2249 16
- 17. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Auto-generate client or server code • Auto-generate client code that consumes the API • Target your script or app programming language • Auto-generate server code as a skeleton of the API • Target the programming language used by engineering groups • Useful to create mock servers BRKDEV-2249 17
- 18. #6. API Mocks
- 19. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Mocking APIs BRKDEV-2249 19
- 20. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Mocking APIs BRKDEV-2249 20
- 21. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Summary OpenAPI Specification to 1. Describe API contracts 2. Author OpenAPI documents 3. Publish documentation 4. Try out an API 5. Generate code 6. Mock APIs BRKDEV-2249 21
- 23. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI Specification (OAS) https://spec.openapis.org/oas/latest.html • Defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. • When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. • An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. 23 BRKDEV-2249
- 24. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Elements of OAS • Info: Provides details about the API, including a title and description • Security: Specifies authorization. Required for interactive documen tation • Paths: What the API can do. Defined by a path + HTTP method (aka verb) + input parameters + one or more response details • Components: Capture reusable elements that may be referenced within and across OAS files. Includes schema, headers, security details BRKDEV-2249 24
- 25. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OAS Elements: Info Example info BRKDEV-2249 25
- 26. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OAS Elements: Servers (aka Hosts) • Describes one or more API endpoints for cloud and on-premises APIs • They may be a complete URL or use variable substitution servers BRKDEV-2249 26
- 27. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OAS Elements: Paths • Operation = Path + HTTP Method • Query parameter • GET /alarms?active=true • 200: Response with payload paths BRKDEV-2249 27
- 28. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OAS Elements: Schema Components • Define reusable structures for request inputs and response outputs. • Often referenced from operations or from one schema to another components BRKDEV-2249 28
- 30. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public The OpenAPI Initiative Charter https://www.openapis.org/ BRKDEV-2249 30
- 31. #9. Versions
- 32. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Versions of the OpenAPI Specifications BRKDEV-2249 full compatibility with modern JSON Schema [Draft 2020-12] OpenAPI 2.0 - 2014 OpenAPI 3.0 - 2017 OpenAPI 3.1 - 2021 32
- 33. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 BRKDEV-2249 33
- 34. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public but… OAS v2.0 still largely spread API Specification Transformation Trends BRKDEV-2249 “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. 34
- 35. #10. Formats
- 36. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public JSON vs. YAML: Side-by-side BRKDEV-2249 36
- 37. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public YAML Syntax String Array of objects (notice the hyphens for each item) Dictionary Array (with hyphens) Condensed Array (square brackets) BRKDEV-2249 37
- 38. #11. Terminology
- 39. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 OpenAPI Documents contain the description of the full set or a subset of the API features. Should be read as: “a file whose contents conform to the OpenAPI Specification” OAS document OpenAPI Document Terminology An API Definition describes the full contract for an API. It consists in a set of OpenAPI documents. A single OpenAPI document is generally sufficient to fully define an API. BRKDEV-2249 39
- 40. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI Terminology • OpenAPI Specification, OpenAPI Initiative, OpenAPI Tools, OpenAPI • OpenAPI/OAS Document: describes an API using the OpenAPI specification • API/OpenAPI Definition, API Specification/Spec • API Endpoint, API: URL at which an API version can be accessed, such as ‘https://api.meraki.com/v1’ • API Documentation: the reference documentation for an API, published on a web site, and kept in sync with a version of an API • API Path, API: a URL such as ‘/organizations’ • API Operation, API: a Path + a method such as ‘GET /organizations’ • API Contract: the paths, operations, schemas, errors in an OpenAPI document • SDK, Client Library, API: ready-to-use code to consume an API 40 BRKDEV-2249
- 41. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 OpenAPI documents for download or online browsing. • Each API version provides developer documentation which includes authentication instructions, developer guides, code samples and reference documentation… and an API changelog. BRKDEV-2249 41
- 42. #12. Lifecycle
- 43. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 revision N 4. Integrate with API documentation publishing toolchain BRKDEV-2249 OpenAPI documents 43
- 44. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public API Lifecycle API Definition OAS document OAS document OpenAPI Documents The API Lifecycle v1 v2 1.1 1.2 API Versions tagged using semver API Changelog describes updates across releases of an API Backward Compatibility across minor versions Major minor BRKDEV-2249 44
- 45. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI Workflows and Best Practices Single Artifact Define where to store your OpenAPI documents • 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 • OpenAPI fundamentals • OpenAPI documents workflow • OpenAPI toolsets (linters, code generators...) Refine the Process Practice and refine as needed • Update OpenAPI documents, review PR and merge changes • Maintain an API Changelog • This workflow may take time to establish BRKDEV-2249 48
- 46. #13. Accuracy
- 47. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Code as the source of truth Convert code comments or annotations BRKDEV-2249 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/ 50
- 48. #14. Linting
- 49. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI Documents Static Analysis Detecting Quality or Security Faults BRKDEV-2249 52
- 50. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 53 BRKDEV-2249
- 52. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public API Changelog • one operation added • one breaking change detected BRKDEV-2249 55
- 54. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Drifts • Import OpenAPI documents • Compare with live traffic observations • Identify Drifts 57 BRKDEV-2249
- 55. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 58 Shadow: undocumented operation BRKDEV-2249
- 56. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 59 Shadow: undocumented query parameter BRKDEV-2249
- 57. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 60 Zombie: deprecated operation still active BRKDEV-2249
- 58. #17. API Lifecycle and Compliance
- 59. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Cisco’s API-First Strategy • Treat APIs as Product • Versioned releases • API Changelogs • Backwards Compatibility • Documentation • Support Backward Compatibility announcement at Partner Summit APIs that are backwards compatible as of October 2022 ▪ Meraki Dashboard API v1 ▪ ISE API v1 ▪ Nexus Cloud API v1 ▪ SecureX ThreatResponse API v1 ▪ Cloud Security Open APIs v2 ▪ Webex API v1 ▪ PX Cloud API v1 BRKDEV-2249 62
- 60. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public API Lifecycle as revisions timeline BRKDEV-2249 63
- 61. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Highly Reliable (Lifecycle with deprecation notices, complete & accurate definition, complete API Changelog) Quality of API Contracts 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 BRKDEV-2249 64
- 62. cs.co/API
- 63. Demo
- 64. #18. Ecosystem
- 65. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI.Tools https://openapi.tools/ BRKDEV-2249 68
- 66. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public OpenAPI Communities BRKDEV-2249 stoplight.io/api-roadmap-ebook 69 techblog.cisco.com blogs.cisco.com/developer
- 67. Wrapup
- 68. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 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 BRKDEV-2249 blogs.cisco.com/developer/worldclassapis01 71
- 69. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Complete your Session Survey • Please complete your session survey after each session. Your feedback is very important. • Complete a minimum of 4 session surveys and the Overall Conference survey (open from Thursday) to receive your Cisco Live t-shirt. • All surveys can be taken in the Cisco Events Mobile App or by logging in to the Session Catalog and clicking the "Attendee Dashboard” at https://www.ciscolive.com/emea/learn/sessions/session- catalog.html 72 BRKDEV-2249
- 70. Continue Your Education © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public 73 Visit the On-Demand Library for more sessions at ciscolive.com/on-demand. Attend any of the related sessions at the DevNet, Capture the Flag, and Walk-in Labs zones. Visit the Cisco Showcase for related demos. Book your one-on-one Meet the Engineer meeting. BRKDEV-2249
- 71. Thank you