Open API Initiative
Dennis BrennanDirector of Engineering
Capital One
Introduction & Agenda
2
▪ Open API Specification (OAS)▪ Open API Initiative (OAI)▪ Using OAS in the Enterprise
The Open API Specificationfka The Swagger Specification
10 December 2014DRAFT - Linux Foundation Confidential 3
What is the OpenAPI Specification?
4
Generally CategorizedREST API Description Language
More GenerallyIDL for REST APIs
What does the OpenAPI Specification Offer?
5
A simple format for creating REST service contracts
▪ Are independent from language, development framework, deployment technology▪ Can be expressed in YAML or JSON format▪ Support both API-first and code-first approaches to
defining, building and documenting APIs▪ Have a clean & powerful extension mechanism
Language Neutral
& Machine Readable Format
APIs can be defined in JSON
or YAML
API-First & Code-First
Development
Powerful Extension
Mechanism
Comprehensive Tooling Support (core, UI, codegen, editor)
Road To the OAS
6
2010 Tony Tam @Reverb founded Swagger
Q1 2015Swagger acquired by SmartBear
Q3 2015 Linux Foundation Workgroup Forms
Q4 2015 Swagger renamed “OpenAPI Specification”
2010 - 2014Development, Growth, Adoption, Tooling, Community
Adoption & Growth
7
▪ 100,000 weekly source visits
▪ 11,500 daily downloads
▪ 10,000 daily visitors to swagger.io
▪ 4,600 forks of official repos
▪ 1,700 public repos on GitHub
▪ Client/server support in all popular
languages & frameworks
Most Popular API Framework
Community
10 December 2014DRAFT - Linux Foundation Confidential 8
Broad Industry Adoption
9
Why adopt the OpenAPI Specification?
10 December 2014DRAFT - Linux Foundation Confidential 10
Commitment to Remain
OpenPortable
Vendor Neutral
Strong Independent Sponsorship
CommunitySimple & Pragmatic
Superior Tooling Best Industry Support
The Open API Initiative
10 December 2014DRAFT - Linux Foundation Confidential 11
The Open API Initiative - MissionProvide an open source, technical community, within which industry participants may easily contribute to building a vendor-neutral, portable and open specification for providing technical metadata for REST APIs – The OpenAPI Specification.
12
OAI initial steps
▪ Swagger Specification donated to the Workgroup
▪ Establishment of a clear, open governance structure for both business & technical direction
▪ Meritocratic approach to technical contributions – not pay-to-play
▪ Charter is here: https://openapis.org/governance
20 August 2015 13Linux Foundation Confidential
OAI Governance Structure
14
Business Governance
Board (BGB)
Budget, marketing, community, etc…
Technical Developer
Community(TDC)
Manages the OpenAPI
Specification
Technical Oversight
Board(TOB)
Resolves conflict in TDC
Swagger ➔ OpenAPI Specification (OAS)
▪ Moved from swagger-api 2.0 to OAI GitHub Repository▪ https://github.com/oai/OpenAPI-Specification
▪ Core TDC elected and working on next version 3.0 of spec
▪ Apache 2.0 License as before
▪ Anyone can join the discussion – please do!
15
Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~June 16
DocumentationStructure
Protocols and Payloads
JSON Schema & JSON
References
URI SupportError
Handling/Documentation
Security Request Parameters
17
Using OAS in the Enterprise
20 August 2015 18Linux Foundation Confidential
What Spec? Spec Generates Code
Spec as Code
Code is Spec
REST API Development Evolution
19
What Spec?
Let’s just code!
20
What about Rest Interfaces?
2010s
21
Let’s put the docs in the
code.
Code is Spec
22
Code First with Swagger Annotations
23
Swagger UI
Build docs by processing
JSON/YAML API Spec
The API Spec can be returned from static source or from the
running API
24
Let’s start with the API
Spec!
Spec Generates Code
25
API First with Swagger Editor
Wrapped Swagger Editor
Lifecycle Tooling
Manage API Metadata
Governance & Review
Dynamic Mock Responses
26
Iterative Codegen Process
27
Let’s Code…a lot less!
Spec as Code
Behavior in API Driven Directly from Spec Reduces Code Generation & Plumbing
▪ Swagger Inflector: Wires API spec to server with programmatic endpoint generation.
▪ Apigee-127: Message validation, OAuth, quota, caching, and other services are all handled through the metadata in your Swagger spec (e.g. OAS Vendor Extensions)
28
Examples
29
OAS Vendor Extensions
Additional data added to API definition to extend the specification
Always prefixed by "x-" and can have any valid JSON format value
30
OAS Vendor Extensions
paths: /demo/bankthings: get: summary: Returns a list of Bank Things operationId: getBankThings x-c1-proxy: audit parameters: - $ref: '#/parameters/ApiKey'
31
From Legacy Java Framework to Polyglot Microservices with the OAS
@Annotations & Servlet Filters ➔ OAS Vendor Extensions
32
Pre/Post Processing based on Servlet Filters
& Annotations
Single Language & Development Framework
Binary Dependencies for Processing Services
33
Pre/Post processing moves to local proxy
(Smart Gateway)
Behavior notated in the API spec with vendor
extensions
Enables more options to build simple APIs
(Dumb API)
Infrastructure & Services instead of
binary dependencies
And Finally…
34
Get Involved!
▪ https://openapis.org/
▪ https://github.com/oai
▪ @OpenApiSpec
35