Presentation at the 2016 Linux Foundation Collab Summit
-
Upload
open-api-initiative-oai -
Category
Technology
-
view
443 -
download
0
Transcript of Presentation at the 2016 Linux Foundation Collab Summit
![Page 1: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/1.jpg)
Open API Initiative
Dennis BrennanDirector of Engineering
Capital One
![Page 2: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/2.jpg)
Introduction & Agenda
2
▪ Open API Specification (OAS)▪ Open API Initiative (OAI)▪ Using OAS in the Enterprise
![Page 3: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/3.jpg)
The Open API Specificationfka The Swagger Specification
10 December 2014DRAFT - Linux Foundation Confidential 3
![Page 4: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/4.jpg)
What is the OpenAPI Specification?
4
Generally CategorizedREST API Description Language
More GenerallyIDL for REST APIs
![Page 5: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/5.jpg)
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)
![Page 6: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/6.jpg)
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
![Page 7: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/7.jpg)
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
![Page 8: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/8.jpg)
Community
10 December 2014DRAFT - Linux Foundation Confidential 8
![Page 9: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/9.jpg)
Broad Industry Adoption
9
![Page 10: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/10.jpg)
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
![Page 11: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/11.jpg)
The Open API Initiative
10 December 2014DRAFT - Linux Foundation Confidential 11
![Page 12: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/12.jpg)
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
![Page 13: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/13.jpg)
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
![Page 14: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/14.jpg)
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
![Page 15: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/15.jpg)
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
![Page 16: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/16.jpg)
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
![Page 17: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/17.jpg)
17
Using OAS in the Enterprise
![Page 18: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/18.jpg)
20 August 2015 18Linux Foundation Confidential
What Spec? Spec Generates Code
Spec as Code
Code is Spec
REST API Development Evolution
![Page 19: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/19.jpg)
19
What Spec?
Let’s just code!
![Page 20: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/20.jpg)
20
What about Rest Interfaces?
2010s
![Page 21: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/21.jpg)
21
Let’s put the docs in the
code.
Code is Spec
![Page 22: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/22.jpg)
22
Code First with Swagger Annotations
![Page 23: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/23.jpg)
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
![Page 24: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/24.jpg)
24
Let’s start with the API
Spec!
Spec Generates Code
![Page 25: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/25.jpg)
25
API First with Swagger Editor
Wrapped Swagger Editor
Lifecycle Tooling
Manage API Metadata
Governance & Review
Dynamic Mock Responses
![Page 26: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/26.jpg)
26
Iterative Codegen Process
![Page 27: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/27.jpg)
27
Let’s Code…a lot less!
Spec as Code
![Page 28: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/28.jpg)
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
![Page 29: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/29.jpg)
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
![Page 30: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/30.jpg)
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'
![Page 31: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/31.jpg)
31
From Legacy Java Framework to Polyglot Microservices with the OAS
@Annotations & Servlet Filters ➔ OAS Vendor Extensions
![Page 32: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/32.jpg)
32
Pre/Post Processing based on Servlet Filters
& Annotations
Single Language & Development Framework
Binary Dependencies for Processing Services
![Page 33: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/33.jpg)
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
![Page 34: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/34.jpg)
And Finally…
34
![Page 35: Presentation at the 2016 Linux Foundation Collab Summit](https://reader031.fdocuments.us/reader031/viewer/2022030402/5871f9c71a28ab5c348b73f9/html5/thumbnails/35.jpg)
Get Involved!
▪ https://openapis.org/
▪ https://github.com/oai
▪ @OpenApiSpec
35