Postman gRPC Testing

gRPC is a fast API technology created by Google. Instead of readable text, gRPC exchanges compact binary messages, and instead of URLs and verbs, it calls named methods on a remote service. Many internal company systems use gRPC for speed. Postman includes a gRPC request type for exploring and testing these services.

The Intercom Picture

A REST API resembles a postal service: addresses, envelopes, and letters. A gRPC service resembles an office intercom with labeled buttons. Press the button called GetUser and the person on the other end responds at once. The labeled buttons are the service methods.

  REST                               gRPC
  ────                               ────
  GET /users/1                       Call UserService.GetUser
  JSON text                          Binary protobuf message
  Many URLs                          One service, many methods
  Request / response                 Four call styles (see below)

What Is a Proto File

A .proto file is the contract of a gRPC service. It defines the services, their methods, and the shape of every message.

syntax = "proto3";

service UserService {
  rpc GetUser (UserRequest) returns (UserReply);
}

message UserRequest {
  int32 id = 1;
}

message UserReply {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

The numbers after each field are tags that identify fields inside the binary message. Postman reads this file and builds a form for each method.

Four Call Types

Type	Pattern	Example
Unary	One request, one response	Fetch one user
Server streaming	One request, many responses	Download a live price feed
Client streaming	Many requests, one response	Upload sensor readings in batches
Bidirectional streaming	Many messages both ways	Live chat

  UNARY               SERVER STREAM        CLIENT STREAM        BIDIRECTIONAL
  C ──► S             C ──► S              C ══► S              C ◄═► S
  C ◄── S             C ◄══ S              C ◄── S              (both talk freely)
                      (many replies)       (many requests)

Create a gRPC Request

1. Click New and choose gRPC.
2. Enter the server address with a port, such as localhost:50051.
3. Switch the lock icon on when the server uses TLS encryption.
4. Load the service definition. Choose Server reflection if the server supports it, or import the .proto file.
5. Select a method from the dropdown list.
6. Write the message in the Message tab.
7. Click Invoke.

Server reflection lets the server describe itself, which spares you from importing files. Many production servers disable reflection, so keep the proto files available.

Write Messages in JSON

Postman accepts a friendly JSON view of the binary message.

{
  "id": 1
}

Click Generate Example Message to produce a template with every field. Replace the sample values with your own data.

Metadata

Metadata plays the role of HTTP headers. Open the Metadata tab and add key-value pairs such as authorization with a bearer token. Keys use lowercase letters.

authorization : Bearer {{token}}
x-request-id  : test-001

Read the Response

The response panel shows the decoded message, the status, and any trailing metadata. gRPC uses its own status codes.

Code	Name	Meaning
0	OK	Success
3	INVALID_ARGUMENT	The message contains a bad value
5	NOT_FOUND	The requested item does not exist
7	PERMISSION_DENIED	The caller lacks rights
14	UNAVAILABLE	The server cannot be reached
16	UNAUTHENTICATED	Credentials are missing or invalid

Test gRPC Responses

pm.test("Call succeeded", function () {
    pm.expect(pm.response.code).to.equal(0);
});

pm.test("User name is a string", function () {
    const reply = pm.response.messages.all()[0];
    pm.expect(reply.name).to.be.a("string");
});

Script object names can differ between Postman versions, so confirm the correct syntax in the snippets panel.

Scenarios to Test

• A valid call returns the expected fields.
• An unknown ID returns NOT_FOUND.
• A missing token returns UNAUTHENTICATED.
• An invalid field value returns INVALID_ARGUMENT.
• A streaming call delivers messages in the correct order.

Key Points

• gRPC calls named methods and exchanges binary messages.
• A proto file defines services and message shapes.
• Unary and three streaming call types cover different data flows.
• Postman loads definitions through reflection or imported proto files.
• Metadata carries authentication, and gRPC status codes report results.