The document discusses OpenAPI and gRPC, two approaches for designing networked APIs, highlighting their specifications, use cases, and code generation tools. OpenAPI, managed by the Linux Foundation, is centered around REST APIs, while gRPC, overseen by the Cloud Native Computing Foundation, employs a messaging system for microservices. The document emphasizes the importance of effective API methodologies and tools to enhance performance and developer experience.

1. OpenAPI and gRPC Side-by-Side
Tim Burks
Google, Inc.

2. I love APIs.

3. 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

4. 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.

5. OpenAPI is owned by the Linux Foundation

6. OpenAPI Adoption

7. 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.

8. gRPC is owned by the Cloud Native Computing Foundation

9. gRPC Adoption
Microservices: in data centres
Streaming telemetry from network devices
Client Server communication/Internal APIs
Mobile Apps

10. What is an API methodology?

11. What is an API methodology?
A collection of tools and practices for building
and using networked services.

12. in depth

13. OpenAPI
API 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.

14. OpenAPI
API Transport Mechanism
HTTP/REST

15. OpenAPI
Data Representation Format
JSON (and more)

16. 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?

17. 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

18. 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.

19. Meet developers where they are.

20. in depth

21. gRPC
Transport Mechanism
Client → Server
Server → Client
Initial
Metadata
MsgMsg
End of
Stream
Status & Trailing
Metadata
Initial
Metadata
MsgMsg Msg
HTTP/2

22. gRPC
Data 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

23. gRPC
API 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) {}
}

24. 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
...

25. 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.

27. 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

28. Build a gRPC service, get a free REST API!

29. Highest performance and quality.

30. Meet developers
where they are.
Highest performance
and quality.

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

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

33. HOW YOU CAN HELP

34. 1. Stop writing interface code by hand.

35. 2. Stop writing interface code by hand.

36. 3. Stop writing interface code by hand.

37. 4. Mind your API methodology.

38. 5. Develop and use API style guides.

39. 6. Use OpenAPI or gRPC.