18 facets of the OpenAPI specification - Cisco Live US 2023
•Descargar como PPTX, PDF•
0 recomendaciones•42 vistas
We introduce the OpenAPI Specification (OAS) and how Cisco Products leverage this industry standard to drive API quality and state-of-the-art developer experience. We present OpenAPI best practices, tools and processes available to the developer community, and some of the benefits for Cisco API consumers. Join this session to discover the misjudged values that come with the OpenAPI specification, and explore the many ways your software development and automation teams can benefit from OpenAPI with better quality and security.
Recomendados
Recomendados
Más contenido relacionado
Similar a 18 facets of the OpenAPI specification - Cisco Live US 2023
Similar a 18 facets of the OpenAPI specification - Cisco Live US 2023 (20)
Más de Cisco DevNet
Más de Cisco DevNet (20)
Último
Último (20)
18 facets of the OpenAPI specification - Cisco Live US 2023
- 1. #CiscoLive Stève Sfartz, Principal Architect @SteveSfartz BRKDEV-2249 DevNet Breakout The 18 facets of the OpenAPI specification
- 2. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive /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 2 BRKDEV-2249 “vision without execution is hallucination” webex: stsfartz@cisco.com github: ObjectIsAdvantag twitter: @SteveSfartz
- 3. #1. OpenAPI to describe API Contracts
- 4. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 4
- 5. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 • An example of OpenAPI document BRKDEV-2249 5
- 7. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 7 Authoring with SwaggerEditor BRKDEV-2249 https://editor.swagger.io/
- 8. Demo
- 10. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive API Reference Documentation developer.cisco.com/meraki/api-v1/#!create-organization • Automated rendering from OpenAPI documents BRKDEV-2249 10
- 11. #4. Try out the API
- 12. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive BRKDEV-2249 12
- 14. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 14
- 15. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 #CiscoLive 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 16
- 17. #6. API Mocks
- 18. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Mocking APIs BRKDEV-2249 18
- 19. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Mocking APIs BRKDEV-2249 19
- 20. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public Summary OpenAPI to describe API contracts author OpenAPI documents publish documentation try out an API generate code mock APIs BRKDEV-2249 20
- 22. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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. BRKDEV-2249 22
- 23. © 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 authorizatio n. Required for interactive docu mentation • 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 23
- 24. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OAS Elements: Info Example info BRKDEV-2249 24
- 25. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 25
- 26. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OAS Elements: Paths • Operation = Path + HTTP Method • Query parameter • GET /alarms?active=true • 200: Response with payload paths BRKDEV-2249 26
- 27. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 27
- 29. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive The OpenAPI Initiative Charter https://www.openapis.org/ BRKDEV-2249 29
- 30. #9. Versions
- 31. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 BRKDEV-2249 31
- 32. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 32
- 33. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive but… OAS v2.0 still remains very present API Specification Transformation Trends “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. BRKDEV-2249 33
- 34. #10. Formats
- 35. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive JSON vs. YAML: Side-by-side BRKDEV-2249 35
- 36. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive YAML Syntax String Array of objects (notice the hyphens for each item) Dictionary Array (with hyphens) Condensed Array (square brackets) BRKDEV-2249 36
- 37. #11. Terminology
- 38. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 38
- 39. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 OAS document • SDK, Client Library, API: ready-to-use code to consume an API BRKDEV-2249 39
- 40. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 40
- 41. #12. Lifecycle
- 42. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 42
- 43. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive 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 revision N 4. Integrate with documentation publishing toolchain OpenAPI documents BRKDEV-2249 43
- 44. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OpenAPI Workflows and Best Practices Source of Truth Define where to store your OpenAPI documents • Single source of truth • OAS documents should be checked into a git repo to track changes Workflow 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 Educate your team members • OpenAPI fundamentals • OpenAPI documents workflow • OpenAPI toolsets (linters, code generators...) Refine 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 47
- 45. #13. Accuracy
- 46. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Code as the source of truth Convert code comments or annotations BRKDEV-2249 49 Python Flask OpenAPI support OpenAPI document API reference documentation
- 47. #14. Linting
- 48. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OpenAPI Linting Static Analysis of an OpenAPI Document 51 Change screenshot > spectral lint --ruleset ruleset.yaml openapi_document.yaml --format pretty -v BRKDEV-2249
- 49. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OpenAPI Linting within your IDE 52 BRKDEV-2249
- 51. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive API Changelog • one operation added • one breaking change detected BRKDEV-2249 54
- 53. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Drifts • Import OpenAPI documents • Compare with live traffic observations • Identify Drifts • Bonus: reconstruction BRKDEV-2249 56
- 54. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Shadow: undocumented operation BRKDEV-2249 57
- 55. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Shadow: undocumented query parameter BRKDEV-2249 58
- 56. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Zombie: deprecated operation still active BRKDEV-2249 59
- 57. #17. API Lifecycle and Compliance
- 58. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Cisco’s API-first Strategy • Treat APIs as Product • Versioned releases • API Changelogs • Backwards Compatibility • Documentation • Support Backward Compatibility Announcement - Partner Summit APIs that are backwards compatible as of October 2022 Meraki Dashboard API v1 ISE API v1 XDR ThreatResponse API v1 Cloud Security Open APIs v2 Webex API v1 PX Cloud API v1 BRKDEV-2249 61
- 59. cs.co/API 62 #CiscoLive © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public BRKDEV-2249
- 60. Demo
- 61. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive BRKDEV-2249 64
- 62. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive API Lifecycle as revisions timeline BRKDEV-2249 65
- 63. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Highly Reliable API Lifecycle with deprecation notices, complete API definition and API changelog Unreliable Breaking changes, no or partial changelog, typically unstructured or UI-led design Evolving Product-tied lifecycle, incomplete API changelog Versioned Product-independent API lifecycle, complete API changelog Trust Quality of API Contracts BRKDEV-2249 66
- 64. #18. Ecosystem
- 65. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OpenAPI.Tools https://openapi.tools/ BRKDEV-2249 68
- 66. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive OpenAPI Communities stoplight.io/api-roadmap-ebook techblog.cisco.com blogs.cisco.com/developer BRKDEV-2249 69
- 67. #19. Bundling
- 68. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Resolving Remote References • OpenAPI documents often include references to simplify their design, collaborative work and maintenance. • Local reference: points to an element within the same file • $ref: '#/definitions/myElement' • Relative reference: points to an element or file on the same server • $ref: '../another-folder/document.json#/myElement’ • URL reference: points to an element located on a different server • $ref: 'https://path/to/your/resource.json#/myElement’ • Tools usually support documents that include local references only. • Tip: OpenAPI resolver utility with a bundling strategy • where relative and URL references are turned to local references 71 BRKDEV-2249
- 70. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive Common OpenAPI Transformations • Resolving References • Merging documents • Splitting into multiple documents • Sorting elements (sections, paths, operations and schemas) • Filtering out specific extensions BRKDEV-2249 73
- 71. Wrapup
- 72. © 2023 Cisco and/or its affiliates. All rights reserved. Cisco Public #CiscoLive APIConsumer • discover the capabilities of an API • automatically generate client code for your preferred language • pivot format to import/export API definitions across tools API Provider • publish accurate and interactive documentation • generate low-level SDKs • automate API changelogs and spot breaking changes • design-first approach with authoring tools • code-first with annotations in the source code • linters to automate compliance with REST conventions • identify security gaps including OWASP Top 10 Security or Compliance Officers • inventory of internal and external APIs • verify backward compatibility across API updates • ensure compliance by integrating with CI/CD pipelines • identify drifts via live traffic observations • check security posture via scanners 75 OpenAPI Benefits BRKDEV-2249
- 74. #CiscoLive
Notas del editor
- At the end of the day, my job at Cisco is to create guidelines for our APIs, And dashboards to track where we are currently and identify where we’ll be in the next 6 months & 18 months in terms of API quality, That requires to define consistent methodology and have execs sponsors to drive changes & transformation as needed in engineering I”ve been seeing great value in the OpenAPI specification, So that OpenAPI is getting central to our internal quality processes. In the next 40 minutes, I hope to give you the materials to ramp you up and share my learnings. Though it’s an introductory session, the presentation will be pretty dense, but should be intelligible to all, and feel free to refer back to it later, as we will go fast on the slides which I provided for backup and to help you continue your journey. And I’ll stay at the end of the session so that we can continue the conversation as needed. No other plans for the next few days. I’ll be in the DeVNet Zone Hello World area for the rest of the week.
- We in DevRel see APIs as contracts Between an organization providing APIs and developers
- IMPORTANT: OAS
- The best way to discover the OpenAPI specifications is certainly to edit and render documents
- Very soon you’ll want to use other editors & renders, but certainly the best / quickest way to start
- https://editor.swagger.io/ swagger: '2.0'info: version: 1.22.0 title: Meraki Dashboard API description: > The Cisco Meraki Dashboard API is a modern REST API based on the OpenAPI specification. Date: 01 June, 2022. [Recent Updates](https://meraki.io/whats-new/) contact: name: Meraki Developer Community url: https://meraki.io/communityhost: api.meraki.combasePath: /api/v1schemes: - httpssecurityDefinitions: meraki_api_key: type: apiKey name: X-Cisco-Meraki-API-Key in: headersecurity: - meraki_api_key: []paths: /organizations: get: description: List the organizations that the user has privileges on operationId: getOrganizations responses: '200': description: Successful operation schema: type: array items: type: object properties: id: type: string description: Organization ID name: type: string description: Organization name url: type: string description: Organization URL api: type: object properties: enabled: type: boolean description: Enable API access description: API related settings licensing: type: object properties: model: type: string enum: - co-term - per-device - subscription description: >- Organization licensing model. Can be 'co-term', 'per-device', or 'subscription'. description: Licensing related settings cloud: type: object properties: region: type: object properties: name: type: string description: Name of region description: Region info description: Data for this organization examples: application/json: - id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term cloud: region: name: North America summary: List the organizations that the user has privileges on tags: - read post: description: Create a new organization operationId: createOrganization parameters: - name: createOrganization in: body schema: type: object properties: name: type: string description: The name of the organization example: name: My organization required: - name required: true responses: '201': description: Successful operation schema: type: object examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term summary: Create a new organization tags: - configure /organizations/{organizationId}: get: description: Return an organization operationId: getOrganization parameters: - name: organizationId in: path type: string required: true responses: '200': description: Successful operation schema: type: object properties: id: type: string description: Organization ID name: type: string description: Organization name url: type: string description: Organization URL api: type: object properties: enabled: type: boolean description: Enable API access description: API related settings licensing: type: object properties: model: type: string enum: - co-term - per-device - subscription description: >- Organization licensing model. Can be 'co-term', 'per-device', or 'subscription'. description: Licensing related settings cloud: type: object properties: region: type: object properties: name: type: string description: Name of region description: Region info description: Data for this organization examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term cloud: region: name: North America summary: Return an organization tags: - read put: description: Update an organization operationId: updateOrganization parameters: - name: organizationId in: path type: string required: true - name: updateOrganization in: body schema: type: object properties: name: type: string description: The name of the organization api: type: object properties: enabled: type: boolean description: >- If true, enable the access to the Cisco Meraki Dashboard API description: API-specific settings example: name: My organization responses: '200': description: Successful operation schema: type: object examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term summary: Update an organization tags: - configure delete: description: Delete an organization operationId: deleteOrganization parameters: - name: organizationId in: path type: string required: true responses: '204': description: Successful operation summary: Delete an organization tags: - configure tags: - name: read - name: configure
- For now, let’s look at the value developers get from these OAS documents
- T
- Generate automatically code that consumes the API
- Generate automatically code that consumes the API
- Mocking example with SwaggerHub using the examples of the OAS doc
- Notice the versions at the top and bottom. Version at the top is the version of the specification Version in the info section is the version of the API Pop quiz about versions?
- If you have the API service is in the cloud, then use the cloud URL. For example meraki uses https://api.meraki.com/ If the API service is on-premise, than this is where you would include the URL to a DevNet Always-on Sandbox so that developers can make requests to a server.
- Operations are defined by a path + HTTP method (aka verb) + input parameters + one or more response details. Operations may also have examples that can assist developers in better understanding how to use the operation effectively
- Components help to capture reusable elements that may be referenced within and across OAS files. Source: https://swagger.io/docs/specification/components/ Schema components define reusable structures for request inputs and response outputs. They are often referenced from operations or from one schema to another. This increases reuse across an API. Likewise, HTTP request and response headers can be reused for things such as conveying rate limits to an API client, authorization token headers, and other important elements
- https://github.com/OAI/OpenAPI-Style-Guide A Short History of the OpenAPI Initiative and the OpenAPI Specification On Nov. 5, 2015, SmartBear in conjunction with 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet announced the formation of the OpenAPI Initiative, an open source project under the Linux Foundation. As part of the formation of the OAI, SmartBear donated the Swagger specification to the Linux Foundation, meaning that the OpenAPI Specification is semantically identical to the specification formerly known as the Swagger 2.0 specification. It is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OpenAPI Specification. In 2010, the Swagger specification was created by Wordnik, who published it under an open source license one year later. In March of 2015, SmartBear acquired Wordnik's interests in the Swagger projects from its parent company, Reverb Technologies.
- https://www.apimatic.io/blog/2022/03/top-api-specification-trends-2019-2022/ As can be seen from the graph above, around the start of 2019, the OpenAPI v3.0 imports were initially less than those of v2.0 (also known as Swagger v2.0). Then, they stayed nearly equal for around four months and eventually rose well above them after August 2019. Meanwhile, the imports of v2.0 slowly declined and are expected to continue their downward trend as more and more people adapt to the newer version.
- While the exact reason is not entirely clear, the apparent reason revolves around the quality of support for OpenAPI v3.0 in tools. OpenAPI v2.0 has been around for much longer than OpenAPI v3.0 so though tools claim to support OpenAPI v3.0 their support for OpenAPI v2.0 may be much more stable and dependable. It is also possible that people are using legacy tools that still only support OpenAPI v2.0.
- 1min B. and the lifecycle, With recommendation to adhere to semantic versions principles
- 1min: which means that along your API lifecycle, you are going to have versions of your OAS documents
- Stève - 2min: the nice thing with a serialized contract for an API, is that you can start doing Analysis, The spectral project from Stoplight has been leading the charge to conduct analysis of OpenAPI document Customizable checks can be created such as design conventions (snake vs camelCase) but also checking error cases are documented spectral lint --ruleset ruleset.yaml compliance-1.22.0-rev1.yaml --format pretty -v
- Stève: 2min At Cisco, we’re committed to an API-first strategy across the Cisco portfolio. As a first step toward Cisco’s API-first strategy, Cisco is committing to rolling out backward compatibility, which ensures APIs continue working with every versioned release. Backward compatibility is central to the design, documentation, and support process of strategic Cisco APIs. This includes implementation of changelogs, appropriate notification timelines for any API changes, deprecation notices, and API versioning. Backward compatibility is rolling out for the following Cisco solutions – Meraki Dashboard API, Cisco Identity Service Engine (ISE) API, Nexus Cloud API, SecureX Threat Response API, Cloud Security Open APIs, Cisco Partner Experience (PX) Cloud API, and Webex API. Future backward compatibility of APIs is planned for a growing list of Cisco solutions and will be announced upon availability. This includes ThousandEyes API, Cisco Spaces API, AppDynamics Cloud APIs, Cisco DNA Center API, NSO Northbound API, Crosswork CNC API, and Cisco SD-WAN (vManage) API Reference announcement: https://newsroom.cisco.com/c/r/newsroom/en/us/a/y2022/m10/cisco-advances-api-first-strategy-to-empower-developers-in-the-digital-economy.html
- https://editor.swagger.io/ swagger: '2.0'info: version: 1.22.0 title: Meraki Dashboard API description: > The Cisco Meraki Dashboard API is a modern REST API based on the OpenAPI specification. Date: 01 June, 2022. [Recent Updates](https://meraki.io/whats-new/) contact: name: Meraki Developer Community url: https://meraki.io/communityhost: api.meraki.combasePath: /api/v1schemes: - httpssecurityDefinitions: meraki_api_key: type: apiKey name: X-Cisco-Meraki-API-Key in: headersecurity: - meraki_api_key: []paths: /organizations: get: description: List the organizations that the user has privileges on operationId: getOrganizations responses: '200': description: Successful operation schema: type: array items: type: object properties: id: type: string description: Organization ID name: type: string description: Organization name url: type: string description: Organization URL api: type: object properties: enabled: type: boolean description: Enable API access description: API related settings licensing: type: object properties: model: type: string enum: - co-term - per-device - subscription description: >- Organization licensing model. Can be 'co-term', 'per-device', or 'subscription'. description: Licensing related settings cloud: type: object properties: region: type: object properties: name: type: string description: Name of region description: Region info description: Data for this organization examples: application/json: - id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term cloud: region: name: North America summary: List the organizations that the user has privileges on tags: - read post: description: Create a new organization operationId: createOrganization parameters: - name: createOrganization in: body schema: type: object properties: name: type: string description: The name of the organization example: name: My organization required: - name required: true responses: '201': description: Successful operation schema: type: object examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term summary: Create a new organization tags: - configure /organizations/{organizationId}: get: description: Return an organization operationId: getOrganization parameters: - name: organizationId in: path type: string required: true responses: '200': description: Successful operation schema: type: object properties: id: type: string description: Organization ID name: type: string description: Organization name url: type: string description: Organization URL api: type: object properties: enabled: type: boolean description: Enable API access description: API related settings licensing: type: object properties: model: type: string enum: - co-term - per-device - subscription description: >- Organization licensing model. Can be 'co-term', 'per-device', or 'subscription'. description: Licensing related settings cloud: type: object properties: region: type: object properties: name: type: string description: Name of region description: Region info description: Data for this organization examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term cloud: region: name: North America summary: Return an organization tags: - read put: description: Update an organization operationId: updateOrganization parameters: - name: organizationId in: path type: string required: true - name: updateOrganization in: body schema: type: object properties: name: type: string description: The name of the organization api: type: object properties: enabled: type: boolean description: >- If true, enable the access to the Cisco Meraki Dashboard API description: API-specific settings example: name: My organization responses: '200': description: Successful operation schema: type: object examples: application/json: id: '2930418' name: My organization url: >- https://dashboard.meraki.com/o/VjjsAd/manage/organization/overview api: enabled: true licensing: model: co-term summary: Update an organization tags: - configure delete: description: Delete an organization operationId: deleteOrganization parameters: - name: organizationId in: path type: string required: true responses: '204': description: Successful operation summary: Delete an organization tags: - configure tags: - name: read - name: configure
- Stève: 1 min: finally, the timeline is critical to check the API Contract lifecycle quality as we need to not only score individual contracts but also track progress across releases and ultimately facilitate creation of 100% accurate changelogs and detect breaking changes.
- As we move up this trust ladder, we also wind up improving the developer experience. Going from unreliable to highly reliable takes a lot of effort and dedication on the part of the development team
- Stève - 1min: There are many benefits, and they differ depending on roles to further dig into the many benefits but also become more familiar with OpenAPI documents and the associated toolsets , join the breakout on Friday.