You must have heard about gRPC and its advantages. Here, I will show you how to build a modern API with Nest.js and gRPC in typescript.
Why gRPC is cool
Why use gRPC? It has a ton of advantages like performance, code generation, streaming, etc. But, for me, the main one is a strict specification. GRPC forces you to write .proto
files that describe your API. This feature let me and my team retain a lot of time. Proto-files are specifications that can be written before the development start, and it may be a single source of truth for API implementors.
Overview
In the first part we will build an API using gRPC as a main communication mechanism.
API specification
Let’s start with composing a .proto file. In this article, API will be able to sum two numbers. The .proto
files consist of two services. The first one is a GatewayService service. The service will be an entry point to the backend API, it can retrieve requested, by client, information from other services. The second service is a SummatorService. This one will provide a Sum
method, that sum all numbers it receives.
Summator
This service must provide a function called Sum
, that can sum all the given numbers and return the result. Let’s start with defining the bootstrap
function to start up the app.
Bootstrap
To start a microservice in Nest.js, it has to be configured with a transport type, an URL it will be host on, a path to a .proto
file with a specification of the service, and a package name.
Controller
The controller, in our case, contains only one method called Sum
. To make a method a gRCP handler, the GrpcMethod
annotation should be used with parameters of a name of a service (SummatorService) in a .proto
specification file and a name of a method (Sum) that is intended to be implemented.
sum
method sum all the numbers from the request:
The Summator service is ready. Let’s move on to the Gateway service.
Gateway
The Gateway service is the front part of the whole API. The part which communicates with the outer world. The service will use gRPC to communicate with the client as well as with the Summator service.
Bootstrap
The service configuration is the same as for the Summator service except the url
field. The url
’s port differs.
Module
To get access to the Summator service client object, it has to be registered first. Client module registration is performed using the register
method of the ClientsModule
class of the @nestjs/microservices
package. It requires a name (any name, used in injection), a transport (GRPC in this case), a path to the .proto
specification file of a service that is being injected, and an URL to the service.
Now, we can inject a ClientGrpc instance using SUMMATOR_PACKAGE as a name of an entity being injected.
Controller
In this case, the controller will provide only one method Add
. This method should take a
and b
numbers from the request body and call the sum
method of the Summator service client instance, that has been configured in the module file.
Unfortunately, all interfaces of requests and gRPC clients that are used are left to define manually. For example, the Add
method’s request type is defined in its .proto
file, but the request’s interface (AddRequest
) in the controller, still should be defined manually. In any big project, you should use tools to generate such interfaces automatically, to avoid all kinds of typos. Protobuf.js is a good one.
In the constructor, ClientGrpc is injected, which was imported in the module file earlier. On module initialization, we get a SummatorServiceClient
object from the injected ClientGrpc.
It’s important to clarify, that the SummatorServiceClient
interface, is defined as a separate interface manually. It maps .proto
Summator service into typescript.
Mostly, Nest.js gRPC methods return rxjs
Observables
. You can work with them reactively, or cast into a promise using toPromise
method.
Summary
I hope, this article helps you to get how easy and useful gRPC is. I totally recommend you to try it out and dive into it.
In part two, I will show you how to integrate a gRPC API with the client app in React.
Part Two — Will be here soon