OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead

TED EPSTEIN, REPREZEN - Ted.Epstein@RepreZen.com
KCDC X - THE KANSAS CITY DEVELOPER CONFERENCE, JULY 2018
1COPYRIGHT © 2018, MODELSOLV, INC. | ALL RIGHTS RESERVED.
OpenAPI v.Next
Events, Alternative Schemas & the Road Ahead

About Me
• Ted Epstein
CEO, RepreZen
◦ Governing Board Member, OpenAPI Initiative
◦ 25+ years in software, including 10 years in
financial services IT
◦ Ted.Epstein@RepreZen.com
COPYRIGHT © 2018, MODELSOLV, INC. | ALL RIGHTS RESERVED. 2

Overview
• APIs: What all the fuss is about
• API Description Languages
• Swagger, OpenAPI 2.0, 3.0 & beyond
COPYRIGHT © 2018, MODELSOLV, INC. | ALL RIGHTS RESERVED. 3http://rzen.io/GetAPIStudio

All Eyes on APIs

How did we get here?
Perfect Storm:
◦ Ubiquitous, standardized
web communication
technology
◦ AJAX: The web works for
data
◦ Mobile
◦ SaaS
◦ Integration “Big Bang”
Result: The API Economy

What does the API Economy look like?
• External APIs:
◦ New Revenue Channels
◦ New Systems of Engagement
• Internal APIs:
◦ SOAP  REST
◦ XML  JSON
◦ Verbs  Nouns
◦ Centralized  Distributed
Interactive
Documentation
Code
Generation
API Testing
Tools
API
Management
API Gateway
Developer
Portal
API Design
Tools
Frameworks
IPaaS
Mocking /
Virtualization
• Tools!
API
Aggregators
http://rzen.io/GetAPIStudio

Oh, and Microservices.
What’s this about?
◦ Componentization, not
centralization
◦ Application-Scoped
◦ Single-Purpose,
Lightweight
◦ Autonomous, Self-
Contained

Oh, and Microservices.
And So…
◦ Network & cloud
infrastructure becomes the
OS
◦ Devops becomes a
prerequisite
◦ Microservice platforms for
orchestration, scheduling,
container lifecycle
management…
◦ Reuse is not a primary
goal… yet.

API Definitions and
Documentation

2000’s - Remember WSDL?
• Web Services Definition Language
◦ W3C Standard
◦ Define your SOAP API contract
(logical & physical)
◦ Widely supported in language frameworks, IDEs
◦ Complex!
◦ XML Schema
◦ Document-Literal, Wrapped, Basic Profile…
◦ WS-*

What About REST?
• Early Days:
◦ XML over HTTP
◦ NoSchema™
• RESTafarians – Hypermedia
as religion
◦ Do you speak HATEOAS?
◦ Hypertext as the engine of
application state
◦ The media type tells the whole
story.

What About REST?
• Then there was WADL…
◦ Web Application Description Language
◦ W3C proposal, never a recommendation
◦ XML-Based
◦ Not widely adopted

2011 – Swagger: The First Generation
• Swagger – First Generation
◦ Aimed at the API documentation
problem – how do I keep the docs in
sync?
◦ Code-first, with annotations
◦ No intermediate language
◦ Runtime with integrated sandbox
testing

2011 – Swagger: The First Generation
• Swagger – First Generation
◦ Aimed at the API documentation
problem – how do I keep the docs in
sync?
◦ Code-first, with annotations
◦ No intermediate language
◦ Runtime with integrated sandbox
testing
“Why WADL when you
can Swagger?”
- Anonymous

2012? API Blueprint
• Apiary introduces API Blueprint
◦ Based on Markdown
◦ Online Editor
◦ Hosted Documentation
◦ Code Generation
◦ Conformance Testing
• Swagger Introduces
JSON Syntax, Editor & Codegen

2013-14: RAML
• MuleSoft introduces REST API
Modeling Language (RAML)
◦ YAML-Based
◦ Traits
◦ Online editors…
◦ Not as widely adopted
• Swagger introduces 2.0 spec
◦ YAML syntax, new editor, codegen,
UI, etc.
◦ Improved language model

2015: OpenAPI
• Swagger 2.0 Specification becomes
the OpenAPI Specification (OAS) 2.0
◦ SmartBear acquires Swagger
◦ Contributes language spec to new
Open API Initiative (OAI), formed under the
Linux Foundation
◦ Founding members 3Scale, Apigee, Capital
One, Google, IBM, Intuit, Microsoft, PayPal
and Restlet
◦ Retains Swagger brand name for its
Commercial & Open Source software

The OpenAPI Initiative (OAI) is a consortium of forward-looking
domain experts who — coming from a wide range of industry
backgrounds — recognize the immense value of standardizing
on how REST APIs are described. With an open governance
structure under the Linux Foundation, the OAI creates, evolves,
and promotes a vendor-neutral, open-source description
format: the OpenAPI Specification. We invite the anyone in the
API community to join us on github.com/OAI/ and to assist in
the development of the OpenAPI Spec.

Swagger or OpenAPI?
Swagger
OpenAPI Initiative (OAI)
OpenAPI Specification (OAS)
(Swagger UI)

Swagger or OpenAPI?
Swagger
OpenAPI Initiative (OAI)
A collection of open source and
commercial software
OpenAPI Specification (OAS)
A cool way to show API documentation
with a built-in “Try it out” button. (Swagger UI)
A brand name trademark owned by
SmartBear
An industry-standard language for
describing REST APIs
An industry consortium formed under
the Linux Foundation

2016: Transitional Year
• RAML 0.8  1.0
(Announced late 2015)
• Oracle acquires Apiary
(Announced Jan 2017)
• OpenAPI begins work on
3.0 spec
• API tools market
expanding & evolving

2017: OpenAPI 3.0
• Industry Converges around
Open API Initiative
◦ MuleSoft joins
◦ RepreZen joins
• More reusable components
• More complete support for JSON
Schema
• Content negotiation
• Enhanced Security Definitions
• More flexible examples
• Callbacks
• Links
• Multiple Servers

OpenAPI v3: More Reusable Components
Reusable Components V2 V3
Path Items  
Parameters  
Responses  
Schema Definitions  
Examples 
Request Bodies 
Headers 
Security Schemes * 
Links 
Callbacks 

OpenAPI v3: More flexible Schemas
Boolean Assertions
◦ allOf (also in 2.0)
◦ anyOf
◦ oneOf
◦ not
additionalProperties
◦ True (default)
◦ False
◦ Subschema
nullable
◦ Allows sending a null value for the
defined schema
readOnly
◦ Now allows
readOnly + required
writeOnly
◦ Only present in the request

OpenAPI v3:
Content
Negotiation
• A request body
can have
different content
for different
media types
paths:
/users:
post:
requestBody:
description: user to add to the system
content:
'application/json':
schema:
$ref: '#/components/schemas/User'
examples:
user:
externalValue: 'http://foo.bar/user-example.json'
'application/xml':
schema:
$ref: '#/components/schemas/User'
examples:
user:
externalValue: 'http://foo.bar/user-example.xml'
'text/plain':
examples:
user:
externalValue: 'http://foo.bar/user-example.txt'

OpenAPI v3: Enhanced Security Definitions
OAuth 2 flows renamed to match
the OAuth 2 Specification:
◦ accessCode is now authorizationCode
◦ application is now clientCredentials.
OAuth 2 security schemes can now
define multiple flows.
Added support for OpenID Connect
Discovery (type: openIdConnect).
API keys can now be sent in: cookie.
securityDefinitions renamed, moved
to components/securitySchemes,
allowing external referencing.
New type: http is an umbrella type
for all HTTP security schemes
◦ Basic
◦ Bearer
◦ other

OpenAPI v3:
Callbacks
• Asynchronous
“outbound” API
notifications, or
webhooks.
• Specifies a client-
provided API that the
server will invoke.
paths:
/streams:
post:
parameters: ...
responses: ...
callbacks:
onData:
'{$request.query.callbackUrl}/data':
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
userData:
type: string
responses:
'202':
description: Data received
'204':
description: Unsubscribe

Links
• “OpenAPI Links are Client-Computed, Design-Time
Parameterized Traversals between Responses and
Operations.”
◦ Client-Computed
◦ Design-Time
◦ Parameterized
◦ From Response
◦ To Operation

Links
Example
/2.0/users/{username}:
get:
operationId: getUserByName
parameters:
- name: username
in: path
required: true
schema:
type: string
responses:
'200':
description: The User
content:
application/json:
schema:
$ref: '#/components/schemas/user'
links:
userRepositories:
# returns array of '#/components/schemas/repository'
- operationId: getRepositoriesByOwner
parameters:
username: "$response.body#/username"

2018: OpenAPI 3.x
• New API Paradigms Emerging
◦ GraphQL
◦ gRPC
◦ Async API
◦ IoT Standards…
• OpenAPI 3.x topics under
discussion:
◦ Alternative Schemas
◦ Conformance Testing & Certification
◦ Overlays
◦ Encryption/Signing
◦ Client Certificates
• 33 members as of May 2018
• Netherlands Government
Standardizes on OpenAPI v3

Alternative Schemas
• Allow non-JSON formats to use format-specific
schema languages.
• Can use anyOf (or another keyword, TBD):
◦ Spec provides a list of schemas
◦ Client can use the first schema that it is able to process.

Alternative Schemas

Client Certificates
• New Security Scheme Type
• Use SSL protocol (HTTPS) to provide a verifiable client
identity
• Same infrastructure already available in browsers and SSL
frameworks:
◦ PKI
◦ Trust Chain
◦ Certificate Store, etc.

Thank you!

OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead

More Related Content

What's hot (20)

Similar to OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead (20)

Recently uploaded (20)

OpenAPI v.Next - Events, Alternative Schemas & the Road Ahead