I Love APIs 2015 API Lab Design-first API Development Using Node and Swagger
The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for...
Transcript of The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for...
The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability
Steven WillmottCEO, 3scale Inc.
[email protected] : @njyx
Credits
2
▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar (Smartbear) and myself
▪ http://openapis.org/
Who Am I?
▪http://www.3scale.net ▪@3scale▪Early Swagger supporter▪Now OAI Founding Member
3
▪CEO of 3scale▪Leading API Infrastructure
Provider▪700+ Customers▪Billions of API Calls Managed
Introduction & Agenda
4
▪OpenAPI Specification (OAS)▪Open API Initiative (OAI)▪Usage and Tooling Examples
The OpenAPI Specificationfka “the Swagger specification”
DRAFT - Open API Initiative (OAI) 5
What is the OpenAPI Specification?
6
Generally CategorizedREST API Description Language
More GenerallyIDL for REST APIs
What does the OpenAPI Specification Offer?
7
A simple format for writing 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
8
2010 Tony Tam @Wordnik 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
9
▪ 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 - Open API Initiative 10
Broad Industry Adoption
11
Why adopt the OpenAPI Specification?
12
Commitment to Remain
OpenPortable
Vendor Neutral
Strong Independent Sponsorship
CommunitySimple & Pragmatic
Superior Tooling Best Industry Support
The Importance of API Interface Definitions
13
14
What about Rest Interfaces?
2010s
15
What Spec? Spec Generates Code
Spec as Code
Code is Spec
REST API Development Evolution
Shared Definitions are Crucial
▪Stable Interface Definition▪Managed process around
change▪Discovery of capabilities▪Automation of processes and
procedures
▪Essential at 100’s APIs ▪Invaluable at 10’s Thousands
and Millions
16Photo: Josh Hibbert / Unsplash.com
In your organization: inter-team dependencies
Across the public Internet: cross-organization discovery & contracts
Shared Definitions are Crucial
▪Fixed point of Reference▪Automation:▪Explorers / Docs▪Code Gen ▪Editors ▪Search ▪Testing ▪Change Management▪Management platforms
▪Design Focus
17
The Open API Initiative
18
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.
19
OAI Initial Steps
▪Establishment of a clear, open governance structure for both business & technical direction
▪Swagger specification donated to the Open API Initiative
▪Meritocratic approach to technical contributions – not pay-to-play
▪Charter is here: https://openapis.org/governance
20
OAI Governance Structure
21
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
▪You can/should join the discussion – please do!
22
Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~mid July23
DocumentationStructure
Protocols and Payloads
JSON Schema & JSON
References
URI SupportError
Handling/Documentation
Security Request Parameters
24
OAS Usage Examples
25
Code First with Swagger Annotations
26
Swagger UI
Build docs by processing
JSON/YAML API Spec
The API Spec can be returned from static source or from the
running API
27
API First with Swagger Editor
Wrapped Swagger Editor
Lifecycle Tooling
Manage API Metadata
Governance & Review
Dynamic Mock Responses
And Finally…
28
Get Involved!Website: https://openapis.org/
Spec: https://github.com/oai
Follow: @OpenApiSpec
29
Additional Information
30
31
OpenAPI Spec’s X-Extensions
Additional data added to API definition to extend the specification
Always prefixed by "x-" and can have any valid JSON/YAML format value
32
OpenAPI Spec’s X-Extensions
paths: /demo/bankthings: get: summary: Returns a list of Bank Things operationId: getBankThings x-c1-proxy: audit parameters: - $ref: '#/parameters/ApiKey'
33
From Legacy Java Framework to Polyglot Microservices using OpenAPI
@Annotations & Servlet Filters ➔ X-Extensions