apidays LIVE Helsinki - APIs, Platforms, And Ecosystems - Transforming Industries And Experiences
Implementing OpenAPI and GraphQL Services with gRPC
Tim Burks, Software Engineer at Google
2. 1. API technologies: OpenAPI, GraphQL, gRPC
2. Why implement your API with gRPC?
3. Implementing OpenAPI services with gRPC
4. Implementing GraphQL services with gRPC
Topics
4. Five Questions about API Systems
1. What problem is this API system addressing?
2. How are APIs called?
3. How are APIs built?
4. What’s great about this?
5. What’s challenging about this?
5. What problem is OpenAPI addressing?
“The OpenAPI Specification, originally known
as the Swagger Specification, is a specification
for machine-readable interface files for
describing, producing, consuming, and
visualizing RESTful web services.”
Wikipedia
6. How an OpenAPI service is called:
You might call it from your browser.
In your applications, you call it from code.
openapi-generator
autorest
APIMatic
SwagGen (Swift)
Paperclip (Rust)
7. How an OpenAPI service is built:
🤞 Code-first
Handwritten implementations.
Handwritten API descriptions.
⚙ Code-first (better)
Handwritten implementations. API
descriptions generated from code.
📐 Spec-first
Handwritten API descriptions.
Implementations generated from API descriptions.
8. What’s great about OpenAPI:
● Standards and tools make it easy to get
started.
○ HTTP
○ JSON/YAML
● Very popular - large community.
9. What’s challenging about OpenAPI:
“Unfortunately, many of the APIs that claim to be
RESTful layer a lot of proprietary concepts on top
of HTTP. Essentially, they invent their own API and
use HTTP as a lower-level transport layer, rather
than using HTTP directly as it was designed. In fact,
there’s so much variability in the way that
people use the term REST in the context of APIs
that it’s difficult to know what they mean by it
unless you know them well.”
Martin Nally
10. What problem is GraphQL addressing?
“GraphQL is a query language for APIs and a
runtime for fulfilling those queries with your
existing data. GraphQL provides a complete
and understandable description of the data in
your API, gives clients the power to ask for
exactly what they need and nothing more,
makes it easier to evolve APIs over time, and
enables powerful developer tools.”
graphql.org
11. How a GraphQL service is called:
“With express-graphql, you can just send an
HTTP POST request to the endpoint you
mounted your GraphQL server on, passing the
GraphQL query as the query field in a JSON
payload.”
https://graphql.org/graphql-js/graphql-clients/
Also GraphiQL!
12. How a GraphQL service is built:
● Code-first, schema extracted from code
● Schema-first - code generated from SDL
● Generated from underlying APIs
○ Federated from other GraphQL APIs
○ OpenAPI-to-GraphQL
○ rejoiner
13. What’s great about GraphQL:
● Simple client-side interface
● Optimizes for client performance
● Layered on familiar technology
● Sharable BFF
14. What’s challenging about GraphQL:
● Complex implementation
● Performance challenges
● Versioning
● Schema design
Public GraphQL APIs are rare.
15. What problem is gRPC addressing?
“gRPC is a modern open source high
performance RPC framework that can run in
any environment. It can efficiently connect
services in and across data centers with
pluggable support for load balancing, tracing,
health checking and authentication. It is also
applicable in last mile of distributed computing
to connect devices, mobile applications and
browsers to backend services.”
grpc.io
16. How a gRPC service is called:
ALWAYS specification-first.
Clients are generated from API
descriptions written in the Protocol Buffer
language.
17. How a gRPC service is built:
ALWAYS specification-first.
Service code is generated. Typically this
generated code declares an interface that is
implemented in language-native data
structures and patterns.
18. What’s great about gRPC:
So much is built-in.
High performance.
Cross-language compatibility.
Potential for very nice client integration.
22. Protocol Buffers is a language-neutral, platform-neutral, extensible
mechanism for serializing structured data.
23. “Protocol Buffers” means several things
1. A serialization mechanism
2. An interface description language
3. A methodology
24. Protocol Buffer Serialization
A message is just a stream of bytes
[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
26. Protocol Buffer Methodology
% protoc echo.proto --go_out=.
# This runs the Protocol Buffer Compiler
# (https://github.com/protocolbuffers/protobuf/releases)
#
# with a plugin called protoc-gen-go
#
# The plugin generates a Go source file that implements
# the data structures defined in echo.proto and code
# for reading and writing them as serialized bytes.
27. gRPC scales to many programming languages.
Java
Service
Python
Service
Go
Service
C++
Service
gRPC
Server
gRPC
Stub
gRPC
Stub
gRPC
Stub
gRPC
Stub
gRPC
Server
gRPC
Server
gRPC
Server
gRPC
Stub
36. GAPICs: Long-Running Operations
SpeechClient speechClient = SpeechClient.create();
OperationFuture<LongRunningRecognizeResponse> recognizeOperation =
speechClient.longRunningRecognizeAsync(config, audio);
…
LongRunningRecognizeResponse response = recognizeOperation.get();
● Java: OperationFuture
○ Polls the service until the LRO is done
○ Provides metadata as the LRO is in progress
○ Provides the final result
40. protoc-gen-go_cli
A protoc plugin that generates
CLIs in Go for APIs described
with protocol buffers.
gRPC supports Generated Command-Line Interfaces.
41. gRPC-Web Supports Browser Apps.
● Call gRPC from Browsers (Javascript, Dart)
● Proxy with Envoy
● Third party implementations
(github.com/improbable-eng/grpc-web)
gRPC Supports Reflection.
● Protocol Discussion
● Go implementation (example)
● Specification (protos)
46. # Call the CreateKiosk method
$ curl -d '{"name":"HTTP Kiosk", "size": { width: 1080, height: 720 } }'
localhost:8082/v1/kiosks?key=AIzaSy[...]bBo
# Call the GetKiosk method
$ curl localhost:8082/v1/kiosks/1?key=AIzaSy[...]bBo
Now you can use HTTP+JSON!
47. gnostic-grpc
● 6 useful things I learned from GSoC
● How to build a REST API with gRPC and get
the best of two worlds
● gnostic-grpc (end-to-end example)
● Envoy gRPC-JSON transcoding
49. Code-first or Schema-first?
● Evolving the Graph (Jon Wong, Coursera)
● Hard-Learned GraphQL Lessons: Based on
a True Story (Natalie Qabazard & Aditi
Garg, Trulia)
● The Problems of "Schema-First" GraphQL
Server Development (Nikolas Burk, Prisma)
56. Impressions / Project Ideas
gRPC has a lot of API information in the .proto files and we
can extend that with annotations.
There are some gaps between GraphQL assumptions and
gRPC practices that we would want to smooth with
configuration or conventions.
We could generate a GraphQL interface directly from gRPC
reflection.
Can we define a standard for gRPC-GraphQL transcoding?