Developing APIs over a RESTful interface with JSON payloads is kind of the de-facto standard nowadays, but it still lacks an easy way to build it with a well-defined interface and document it to be used by others. What if we can leverage gRPC's fast, type-safe, and modern way of building APIs and still be able to provide an interface over REST/JSON ? Check this talk to find out how.

1. https://www.google.com/url?
sa=i&url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWebAssembly&psig=AOvVaw01ph2uPKCm79kmbF
AW&ust=1594860562007000&source=images&cd=vfe&ved=0CAIQjRxqFwoTCOCK-
dyEzuoCFQAAAAAdAAAAABAD
Alvaro Viebrantz
Google Developer Expe
rt
for IoT and Founding Engineer at golioth.io
aviebrantz.com
@alvaroviebrantz
Building REST APIs using
gRPC and Go

2. CURRENT STATE OF REST APIS

3. What is a REST API ?
Usually follow some conventions
• API using the most of the HTTP Spec
• HTTP Verbs to de
fi
ne methods
• Leverage HTTP Response codes
• URL to de
fi
ne resource location
• Content-Type/Accept Headers to de
fi
ne serialization/format
HTTP Method Action URL
GET List Books https://example.com/api/books
GET Get a book https://example.com/api/books/{id}
POST Create a book https://example.com/api/books
PUT Update a book https://example.com/api/books/{id}
DELETE Delete a book https://example.com/api/books/{id}

4. JSON over HTTP
Most REST APIs are just JSON being transferred over HTTP
• Human Readable
• Native to Javascript and browsers. JSON is supported natively everywhere
• Problems
• Poorly typed - How do I know which types to send to the API ?
• Expensive marshaling
• Not type safe and hand made validation
• Some solutions - Add more docs on top of it
• OpenAPI / Swagger docs
• JSONAPI Spec

7. SO THE SOLUTION IS TO
WRITE MORE YAML/JSON ?
YES
😞 😞 😞

8. gRPC API

9. What is a gRPC API ?
High performance Remote Procedure Call framework
• Uses HTTP/2 for transport
• Bi-directional streaming between client and server
• Build on top of Protocol Bu
ff
ers
• Binary format to transfer data
• Fast and low overhead
• IDL to de
fi
ne messages
• Single Source of Truth
• Type-safe
• Generators for multiple programming languages and platforms
grpc.io

10. Building an API with gRPC
Steps for building an API
• De
fi
ne a service in a .proto
fi
le using Protocol
Bu
ff
ers IDL
• Generate server and client stub using the
Protobuf compiler
• Extend/Implement your business logic in the
language that you choose for the server
• Call the service using the
generated client
grpc.io

11. Protocol Buffers
Language neutral structured data definition

12. De
fi
ning Services
Using the same IDL from Protobuf

13. Compiling and implementing Services
Just fill with you business logic

14. Use the generated client
No need to write code to connect your app to your server

15. Problems with gRPC
Of course, everything has pros and cons
• Not supported directly in the browser
• You need a proxy to convert from HTTP/2 to HTTP/1.1
• gRPC-Web, Envoy Proxy and others solve that
• That alone is already a big issue.
• A lot of public facing APIs are expected to be a HTTP+JSON API

16. USING THE BEST OF BOTH WORLDS
gRPC Gateway

17. gRPC-Gateway
github.com/grpc-ecosystem/grpc-gateway
• Protocol bu
ff
ers plugin
• Translates HTTP+JSON requests to
gRPC back and forth
• HTTP Status codes
• HTTP Headers
• Add annotations to your proto
fi
les
and you are good to go
• Generates Swagger/OpenAPI
de
fi
nitions
• Currently generates server code in
Go, but in theory can generate to
other languages in the future

18. Demo
TV Time API
github.com/alvarowolfx/go-grpc-rest-api-demo

19. TV Time API
Track your favorite Movies and TV Shows
• Create an account
• Login ( get a JWT Token )
• List catalog entries
• Create catalog entry 🔒
• Add/Remove from your favorite list 🔒
• List Favorites 🔒
github.com/alvarowolfx/go-grpc-rest-api-demo

20. gRPC Services
Auth, Users and Catalog services

21. gRPC Services
Auth, Users and Catalog services

22. OpenAPI/Swagger Annotations
Extra annotations to allow the same gRPC server to be accessed via a REST API

23. OpenAPI/Swagger Annotations
Annotations to add more metadata to Swagger output

24. OpenAPI/Swagger Security Requirements
Let us mark which methods need to be called with authentication

25. Authentication Interceptor
github.com/grpc-ecosystem/go-grpc-middleware

26. OpenAPI/Swagger Output
You can try it out on Swagger UI

27. OpenAPI/Swagger Output
You can try it out on other UI

28. Demo
github.com/alvarowolfx/go-grpc-rest-api-demo

29. References

30. References
• Talk Demo - github.com/alvarowolfx/go-grpc-rest-api-demo
• grpc.io
• github.com/grpc-ecosystem/grpc-gateway
• github.com/johanbrandhorst/grpc-gateway-boilerplate
• Videos
• https://www.youtube.com/watch?v=AaqZvsrULi4
• https://www.youtube.com/watch?v=Zf9G2KzYs7w
• https://www.youtube.com/watch?v=Pq1paKC-fXk
github.com/alvarowolfx/go-grpc-rest-api-demo

31. Thanks!
aviebrantz.com
youtube.com/alvaroviebrantz
twitch.tv/alvaroviebrantz
Alvaro Viebrantz
Google Developer Expe
rt
for IoT and Founding Engineer at golioth.io
aviebrantz.com
@alvaroviebrantz