TechCorp now has its two main channels: REST/JSON for synchronous calls (03-01) and RabbitMQ for events (03-02). With those you can build the whole system, and in fact that is what we will do in module 4. But it is worth knowing two alternatives that solve specific problems REST/JSON solves poorly: gRPC, for high-volume internal calls with a typed, binary contract, and GraphQL, so that a front end can request exactly the data it needs from several services in a single query. They are neither fads nor replacements for REST: they are tools with a clear niche, and knowing what it is prevents both ignoring them and using them where they do not belong.

In this lesson we will look at which limitations of REST/JSON motivate each alternative; gRPC with Protocol Buffers (a real .proto for the Inventory service), HTTP/2, the four call types, and a minimal server and client in Node.js with @grpc/grpc-js explained line by line; GraphQL with a schema of orders and products, resolvers, the N+1 problem and DataLoader; a comparison table of REST, gRPC, GraphQL and messaging; and TechCorp's decision on where each one fits. The gateway and the BFF (where GraphQL would shine) belong to 03-04, and versioning of .proto files and GraphQL schemas, to 03-06.

1. Limitations of REST/JSON that motivate alternatives
2. gRPC: what it is and how it works
3. Protocol Buffers: Inventory's .proto contract
4. gRPC server and client in Node.js
5. Errors in gRPC and when to use it
6. GraphQL: schema, queries and mutations
7. Resolvers in Node.js
8. The N+1 problem and DataLoader
9. When to use GraphQL and its risks
10. Comparison: REST, gRPC, GraphQL and messaging
11. TechCorp's decision

REST over JSON is the de facto standard because it is simple, universal and readable. Precisely because of that it has three shortcomings that become noticeable as a system grows:

gRPC attacks the first two (compact binary, HTTP/2 and a contract generated from a .proto). GraphQL attacks the third (the client declares the exact shape it wants). Neither attacks all three, and neither solves what messaging solves (temporal coupling).

gRPC is a remote procedure call (RPC) framework created by Google. Its ingredients:

• Contract first. You write a .proto file that defines the services, their methods and the messages they exchange. From it, server and client code is generated in whatever language (Node.js, Go, Java...). The contract is not documentation: it is the source.
• Protocol Buffers (protobuf) as the serialization format: binary, compact (an int32 takes 1-5 bytes; in JSON, "quantity": 2 takes 13), and with a schema (the receiver knows the type of every field without guessing).
• HTTP/2 as the transport: a single TCP connection multiplexes many calls in parallel, headers are compressed, and there is native streaming in both directions.
• Four call types:

The right mental model: gRPC is like calling a function that lives in another process, with types checked at compile time (or at load time, in Node.js). REST is like manipulating documents. That is why gRPC fits internal service-to-service calls and REST fits public APIs.

In 03-01 we designed POST /reservations as Inventory's REST contract "in case the Orders↔Inventory relationship becomes synchronous". This is the same contract in gRPC:

How to read it:

• syntax = "proto3" is the current version of the language. package provides a namespace (and, with v1, leaves room for versioning, the subject of 03-06).
• service groups the rpcs. Each rpc has an input message and an output message; stream in front of one of them turns it into a stream.
• message is like a struct. Each field carries a type (string, int32, bool, repeated X, another message, enum), a name in snake_case (the protobuf convention; the generated code converts it to camelCase in JavaScript if asked to) and a field number unique within the message. That number is the field's identity in the binary: changing the name breaks nothing; changing the number does.
• In proto3 all fields are optional and have a default value ("", 0, false, empty list). There is no null: you have to decide how to represent "absent" (with optional, available since protobuf 3.15, or with a wrapper message).
• enums must have a 0 value, which is the default; by convention it is named *_UNSPECIFIED to tell it apart from a real value.

Notice that this .proto is the contract between Orders and Inventory: if Luis's team and the Inventory team (which in 02-01 we saw are the same team) agree on it, each generates its side and works in parallel.

In Node.js there are two ways to use a .proto: generate static code with protoc and the JavaScript plugin, or load it dynamically at runtime with @grpc/proto-loader. The second is the simplest for learning and the one we will use; in production TechCorp would also use dynamic loading unless it needs generated TypeScript types.

Server (inside inventory-service; only the gRPC part, the rest of the service belongs to module 4):

Client (inside orders-service):

And its use, with our usual order:

The essentials: the .proto is the only shared file; server and client load it and get typed objects; the method and field names come from the contract, not from a hand-written URL; and the deadline is the equivalent of the AbortSignal.timeout from 03-01.

gRPC does not use HTTP codes: it has its own, fewer and more precise. The ones TechCorp maps:

The business code (OUT_OF_STOCK) travels in details or, better, in a structured error message (google.rpc.Status with typed details); for TechCorp the prefix in details plus a mapping in the client is enough.

When to use gRPC:

• Internal service-to-service communication with high volume or a low-latency requirement: binary serialization and HTTP/2 become noticeable from thousands of calls per second upward.
• When you want a strong contract and generated code in several languages (teams with Go, Java and Node.js).
• Streaming (progress, real-time tracking).

When not to:

• Public APIs consumed by browsers: browsers do not speak native gRPC (gRPC-Web exists with a proxy, but it adds parts), and external developers expect REST.
• When readability matters more than performance: you cannot curl it and read the response.
• Small teams without a performance problem: it is complexity with no return.

For TechCorp: Orders → Inventory is the natural candidate if it ever becomes synchronous (partnership from 02-03, same team, frequent calls). Today it goes through events and will stay that way; the .proto is designed and ready.

GraphQL is a query language for APIs and a runtime that executes them. The central idea: the server publishes a typed schema of everything that can be requested, and the client sends a query describing exactly the shape of the response it wants. A single endpoint (POST /graphql), a single round trip, not one field more or less.

Schema (SDL, Schema Definition Language) for an orders view that combines data from Orders and from Catalog:

How to read it: type defines objects with typed fields (! = non-null; [X!]! = non-null list of non-null elements); Query holds the reads and Mutation the writes (both are just special types); input types are for arguments; enum as in protobuf. Notice OrderLine.product: a field that crosses services. It is what REST does not give you without a bespoke endpoint.

The mobile client's query for the order detail screen:

With {"id": "ord-88213"} as variables, the response has exactly that shape:

No customerId, no shippingAddress, no createdAt: they were not requested. And a mutation:

The schema says what can be requested; the resolvers say how each field is obtained. A resolver is a function (parent, args, context, info) per field; those not defined resolve by default by reading the property of the same name on the parent object. We will use graphql-yoga, a lightweight GraphQL server that mounts on Express (Apollo Server is the better-known alternative and equivalent for what we do here):

The chain for OrderDetail: the engine calls Query.order (one REST call to Orders), gets the order with its two lines, and for each line calls OrderLine.product. Without further care, that is two calls to Catalog (one per line) on top of the one to Orders; with 20 lines, twenty. It is the N+1 we already avoided in REST with ?ids=; in GraphQL it must be avoided with DataLoader.

DataLoader is a small library (created by Facebook alongside GraphQL) that does two things: it batches every call to .load(id) that happens in the same event-loop tick into a single call to your batch function, and it caches per request so as not to request the same id twice.

With this, the OrderDetail query makes exactly two REST calls (Orders and Catalog) regardless of the number of lines. Two rules: the DataLoader is created per request (in the context), never globally (the cache would leak data between users and would not refresh), and its batch function must respect the order of the ids.

When yes:

• Aggregation for front ends: an app or website with many screens that combine data from several services and evolve at different paces. The client requests what it needs without the back end creating one endpoint per screen. This is the case of the BFF we will see in 03-04: GraphQL is an excellent way to implement it.
• Clients with limited bandwidth (mobile) where over-fetching is costly.
• When the front-end and back-end teams want to decouple their pace: the back end publishes the schema; the front end decides what to query.

When not:

• Between internal services: services do not need flexibility of shape; they need stable, simple contracts (REST or gRPC) or events.
• As the single facade of the whole system ("one graph to rule them all"): it ends up being a schema monolith maintained by a bottleneck team.

Risks that must be managed from day one:

Marta and the team leads set the protocol policy:

The rule that sums up the decision: no new protocol is introduced until there is a measured problem that REST + events do not solve. gRPC and GraphQL remain known tools with a reserved place, not decisions made out of fashion.

• Adopting gRPC "because it is faster" without measuring. If Orders → Catalog makes 50 calls per second, JSON is not your problem. Measure first (06-04).
• Reusing field numbers in a .proto or changing the type of an existing field. The old receiver will interpret bytes with the wrong meaning. It is covered in depth in 03-06; for now: new numbers, always.
• Forgetting the deadline in the gRPC client. Same as fetch without signal: the call can hang indefinitely.
• GraphQL without DataLoader. The N+1 in GraphQL is silent: in development, with two lines, you do not notice; in production, with twenty, it is a storm of requests to Catalog.
• GraphQL without complexity limits. It amounts to exposing an arbitrary query to the Internet. Maximum depth and maximum cost from the first deployment.
• Global DataLoader (shared across requests). It caches one user's data for another and never refreshes. One per request, in the context.
• Using GraphQL between internal services. It adds a resolution layer and loses the simplicity of REST/gRPC without gaining anything: services do not need to choose the shape.
• Ignoring errors in the GraphQL response. data can come with partial nulls and the error be in another list. Clients must look at both.

Exercise 1. Add to Inventory's .proto a unary method ReleaseReservation that receives the reservation id and a reason (OUT_OF_STOCK, PAYMENT_REJECTED, PAYMENT_TIMEOUT, CUSTOMER_CANCELLATION) and returns the reservation with status RELEASED. Define the messages with correct field numbers, an enum for the reason, and write the server implementation with the appropriate gRPC codes for: nonexistent reservation, reservation already CONSUMED (cannot be released), and success.

Exercise 2. Extend the GraphQL schema with type Payment { id: ID!, status: PaymentStatus!, amount: Float!, method: String! } and PaymentStatus (the statuses from 02-03), and add the field payment: Payment to Order. Write the Order.payment resolver using a DataLoader over a client paymentsApi.getPaymentsByOrders(orderIds) (GET /payments?orderIds=) and explain why the field must be nullable.

Exercise 3. For each scenario, choose REST, gRPC, GraphQL or messaging and justify it in two sentences: (a) the physical warehouse sends 50,000 stock movements every night from a Java system; (b) an external partner wants to check the status of its orders from its ERP; (c) the internal admin website shows a dashboard with the day's orders, their payments and the associated reservations; (d) when an order is confirmed, the invoice has to be generated in a future Billing service.

Solution 1.

Important detail: releasing an already-released reservation responds OK with the same reservation, not FAILED_PRECONDITION: the operation is idempotent by design, consistent with the at-least-once redelivery from 03-02.

Solution 2.

Nullable for two reasons: business-wise, a PENDING or STOCK_RESERVED order does not have a payment yet (the saga has not got there); and resilience-wise, if Payments does not respond, GraphQL can return the order with payment: null and an entry in errors instead of failing the whole query. A non-null Payment! would propagate the null upward and null out the entire order.

Solution 3.

(a) gRPC with client streaming (ImportStock(stream Movement)): high volume, a client in another language that generates its code from the same .proto, compact binary for 50,000 messages. Valid alternative: a batch file; but if an API is wanted, gRPC. (b) REST/JSON: external partner, generic ERP, needs curl, OpenAPI and caching; it is the public API through the gateway. (c) GraphQL in an admin BFF: one screen that aggregates three services with a changing shape; with DataLoader over GET /orders, GET /payments?orderIds= and the Inventory contract. Acceptable alternative: a REST composition endpoint in the BFF, if the dashboard is stable. (d) Messaging: Billing subscribes to order.confirmed on a billing.orders queue; Orders neither changes nor knows Billing exists (03-02, exercise 1).

REST/JSON has three clear shortcomings (verbosity, weak contract, fixed response shape) and we have seen the tool that solves each one. gRPC brings a .proto contract from which the code is generated, binary serialization and HTTP/2 with streaming, and fits high-volume internal calls; we have written the InventoryService with ReserveStock and CheckAvailability, its server and client with @grpc/grpc-js and @grpc/proto-loader, and the mapping of its error codes. GraphQL brings a typed schema from which the client requests the exact shape it needs, and fits aggregation for front ends; we have written the orders and products schema, resolvers with graphql-yoga and the solution to the N+1 with a per-request DataLoader. TechCorp's decision: public REST, events between services, gRPC as a candidate for Orders↔Inventory and GraphQL as a candidate for the mobile BFF, adopting nothing until a measured problem justifies it.

That BFF, and the API Gateway on port 8080 we have been talking about since 02-02, are the next topic: which problems a single entry point solves, what it should do (route, authenticate, rate-limit, aggregate) and, above all, what it should not do, how one is implemented in Node.js or declared in Kong or Traefik, and why each type of client (web, mobile) deserves its own backend for frontend.