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

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!