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.
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
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/
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 documentCustomizable 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.