OpenAPI and gRPC Side by-Side

OpenAPI and gRPC Side-by-SideTim BurksGoogle, Inc.

I love APIs.

I’m talking about Networked APIs.

Application Programming Interfaces that operate across a network of computers. They communicate using network protocols including HTTP, and are frequently produced by different organizations than the ones that consume them.

Google API Design Guide: Glossary

The OpenAPI Specification

Industry standard format for describing REST APIs.

Originally designed for documentation, now with many other applications: API authoring, validation, documentation, analysis, search, testing, mocking, management, code generation.

OpenAPI is owned by the Linux Foundation

OpenAPI Adoption

gRPC

Open-Source messaging system based on Google’s internal API architecture.

Used for code and documentation generation, API management, and support services for APIs and microservices running at very large scale.

gRPC is owned by the Cloud Native Computing Foundation

gRPC Adoption

Microservices: in data centres

Streaming telemetry from network devices

Client Server communication/Internal APIs

Mobile Apps

What is an API methodology?

What is an API methodology?

A collection of tools and practices for building and using networked services.

in depth

OpenAPIAPI Description Language

JSON/YAML-based description format

● Easy for humans to read and write.● Easy to import into most programming languages.● Can be tedious in strongly-typed languages.

OpenAPIAPI Transport Mechanism

HTTP/REST

OpenAPIData Representation Format

JSON (and more)

OpenAPI Code Generation

● swagger-codegen (Open source, Smartbear + community)○ 70+ targets○ First commit: July 6, 2011○ Used by Lyft and Square to generate SDKs

● AutoRest (Open source, Microsoft)● oas-nodegen (Open source, Capital One)● APIMatic (Proprietary, APIMatic)

more?

swagger-codegen often isn’t used “out of the box”:

“Generating client libraries involves customizing the provided language-specific templates…

The amount of modification each template needs varies by language and we’re looking forward to working with the Swagger Codegen community to share our refinements.” Val Polouchkine, Lyft

“...Swagger Codegen is a pretty active project. If you don’t check in your templates, things are gonna break unexpectedly because Swagger Codegen just uses the latest and greatest templates that are out there. So if you don’t sort of manually make sure that those things work, you’re gonna have an issue there.” Tristan Sokol, Square

Monolithic code generators are hard.

● Long build times: changing one target requires rebuilding everything.● Long test times: new builds must be tested for every target language.● For stability, teams may prefer to archive their own generator builds.● Forks will abound.● Quality is uneven.● Versioning is hard.● Complexity and potentially unfamiliar build systems deter contributors.

Meet developers where they are.

in depth

gRPC Transport Mechanism

Client → Server

Server → Client

Initial Metadata MsgMsg End of

Stream

Status & Trailing Metadata

Initial Metadata MsgMsg Msg

HTTP/2

gRPCData Representation Format

Protocol Buffers, streams of bytes in a simple format:

[field_number<<3 + wire_type] [length if necessary] [data]...

$ hexdump /tmp/request.bin 0000000 0a 05 68 65 6c 6c 6f

0a is “0000 1010”, so

field_number = 1 and wire_type = 2

gRPCAPI Description Format

package echo;

message EchoRequest { string text = 1;}

message EchoResponse { string text = 1;}

service Echo { rpc Get(EchoRequest) returns (EchoResponse) {} rpc Update(stream EchoRequest) returns (stream EchoResponse) {}}

gRPC Code Generation

$ protoc echo.proto -o echo.out --swift_out=.

$ which protoc-gen-swift../bin/protoc-gen-swift

$ more echo.pb.swift // DO NOT EDIT.//// Generated by the Swift generator plugin...// Source: echo.proto...

Why does protoc have a plug-in architecture?

● Fast build times: changing one target only requires rebuilding its plugin.● Fast test times: new builds need only be tested for the affected targets.● For stability, teams can archive their own protoc and plugin builds.● New plugins can abound.● Separately-maintained plugins can offer different maturity levels.● Separately-maintained plugins can be appropriately versioned.● Separately-maintained plugins can be in languages that contributors

prefer.

Cross-Language Interoperability

Java Service

Python Service

GoLang Service

C++ Service

gRPC Service

gRPC Stub

gRPC Stub

gRPC Stub

gRPC Stub

gRPC Service

gRPC Service

gRPC Service

gRPC Stub

Build a gRPC service, get a free REST API!

Highest performance and quality.

Meet developers where they are.

Highest performance and quality.

Improve OpenAPI with strongly typed representations, high-quality code generation, and commitment to methodology.

Improve gRPC with dynamic modeling, lighter-weight infrastructure, and simpler tooling.

HOW YOU CAN HELP

1. Stop writing interface code by hand.

2. Stop writing interface code by hand.

3. Stop writing interface code by hand.

4. Mind your API methodology.

5. Develop and use API style guides.

6. Use OpenAPI or gRPC.