openapi spec at google (open api initiative meetup on 2016-09-15)

Dan Ciruli (@danciruli)Product Manager

OpenAPI @ GoogleWhat we’re doing with the baddest spec around

01 API Descriptions at GoogleWhere have we been?

3

Our own format...

While Tony Tam was creating Swagger...

In 2010, Google APIs team launched infrastructure based on the Discovery Format -- a JSON format

Google Cloud Platform 4

Why?

Necessity No standard

5

Discovery Document

A substantial amount of infrastructure was written based on it:

Some visible● Client library generation (10 languages)● APIs Explorer● Discovery service● Documentation generation

Some not visible● Proxy (translates JSON over HTTP to proto

over stubby), capable of X million requests per second


What went well...● Over 150 public APIs● Hundreds of thousands of developers● Many billions of API calls...every day.

What didn’t go so well...● Didn’t work with the open source community

Post Mortem

7

Our own format (cont’d)...

In 2015, in response to a need for lower latency, more efficient data, and HTTP/2 features like bi-directional streaming, we introduced gRPC.

But...all done in open source this time!

02 Why did Google join OAI?History and Status


Open = better

10

Toolchains & APIs matter

Photo credit: Modnar

https://morguefile.com/creative/Modnar

03 OAS at GoogleWhat’s happening now and where are we going?

12

Kubernetes

Kubernetes is an open source container management system, initially released in 2014.

Kubernetes.io publishes all APIs in Swagger (currently 1.2, will upgrade to publish v2.0 as of kubernetes 1.5).

Kubernetes server publishes Swagger specs and ships with Swagger UI

https://github.com/kubernetes/kubernetes/issues/13414#issuecomment-246471582


gRPC APIs are serving Open API specs

One of the features of our new API infrastructure is serving multiple description formats...including OpenAPI specs.

https://cloudfunctions.googleapis.com/$discovery/swagger2?version=v1




Google API Compiler

Open source compiler that takes OAS files (or .proto + YAML) and generates Google API Service Configurations

Service Config is used by various downstream systems (client library generation, documentation gen, etc).

Open sourced here, more tools to come.

https://github.com/googleapis/api-compiler


Cloud Endpoints

● API Management● Server-local proxy● All configuration happens through

Open API spec


Dashboards and UI

Configuration (access, auth, etc) enforced at runtime

Documentation generation and API Explorer delivered via two toolchains (see next slide)

NGINX-based proxy built-in to App Engine,a available in a

container in a GKE pod or GCE.

Cloud Endpoints


Why server-local proxy?

Extremely thinEliminates network hop

Scales with your app

<1 ms latency


JSON-HTTP/1.1

Use Open API specs to manage RESTful APIs written in any language and with

any framework.

proto-HTTP/2

Use gRPC to build highly efficient

HTTP/2-based APIs

Cloud Endpoints: Choose your protocol


$ lspackage.json high-score.js high-score-open-api.yaml app.yaml

$ gcloud app deployRecognized a [node] applicationRecognized an [OpenAPI] API spec Building app image… doneDeploying app image to[http://high-score.stannrapis.com]… doneNow serving API at[http://high-score.stannrapis.com]… doneManage the API at[console.developers.google.com]

$ curl high-score.stannrapis.com/v1/scores/0{ “highscores”: [

{“score”:125239, “player”:“dwc”},{“score”:124231, “player”:“jta”}

]}

1. System detects an Open API spec (yaml) with app

2. Does normal App Engine Flex app package & deploy

3. Spins up additional proxy container with GAE container, applies control plane

4. API is served, listed in Cloud Console user interface

04 What’s next?What’s happening now and where are we going?


API


APIs are...big at Google

Open Source● Both Apigee and Google were

founding members of the Open API Initiative

● We will undoubtedly continue to work both with the spec and with various open source projects related to it

● Google Cloud is committed to being the open cloud -- contributing to existing products, open sourcing internal technologies, creating new projects


How do you represent a more RPC-style API in the spec? How about proto? Could there be a canonical representation of a gRPC API in Open API?

Can our experience with code gen be useful?

Can we represent the richness of the Discovery Document in Open API?

Issues important to us

Thanks!

@danciruli@googleapis

Build what’s next.

Confidential & ProprietaryGoogle Cloud Platform 26

openapi spec at google (open api initiative meetup on 2016-09-15)

Data & Analytics