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