openapi and grpc side by-side
TRANSCRIPT
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.
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 Adoption
Microservices: in data centres
Streaming telemetry from network devices
Client Server communication/Internal APIs
Mobile Apps
What is an API methodology?
A collection of tools and practices for building and using networked services.
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.
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.
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!
Improve OpenAPI with strongly typed representations, high-quality code generation, and commitment to methodology.