Manage service definitions for gRPC requests in Postman

gRPC is a schema-driven framework. This means the client and server must adhere to a standard agreement (schema) while invoking and executing a request. A service definition enables this. On the client side, a service definition makes the client aware of the server's supported services, methods, fields, data types, and message payload structure. Anything that doesn't follow the regulations enforced by the service definition would result in an error. During the execution of the request, the service definition is used to serialize the information exchanged between both parties.

gRPC uses protobuf (protocol buffers) as the Interface Definition Language (IDL) to define the service definition. While creating a gRPC request, you will need to add a service definition to the request (or use server reflection) before selecting a method to invoke. You can configure the service definition from the Service definition tab in a gRPC request.

While creating a new request, if a service definition isn't configured or available through server reflection, Postman prompts you to configure it when you select the Method selection dropdown list. This interface serves as a quick way to add your service definition and move on to invoking your request. From this menu, you can select a protobuf API available in your workspace or import a new one from your local system.

To load a service definition to the request, you can either use server reflection to load the service definition, or use a protobuf API as the service definition.

Using server reflection

If enabled by the server, server reflection can be the easiest way to add the service definition to the client. It fetches the latest information available in the schema from the server without requiring you to manually load a .proto file or create a protobuf schema. Enter the URL and Postman loads the service definition automatically.

Using a protobuf API

If server reflection isn't enabled by the server, you can use a protobuf API as a service definition for the request. For this, you can either select an existing protobuf API in your workspace or import a .proto file as a protobuf API into Postman.

Selecting an existing protobuf API from the workspace

Go to the Service definition tab and select Select a Protobuf schema or paste a link to one. This opens the API selection dropdown list where you can browse through the available APIs and select the one you want to use.

While testing the services, you can also switch to a different version of the selected API by selecting the Version selector next to the API name.

Importing a .proto file

If you don't have the protobuf API available in your workspace, you can also import a .proto file as a protobuf API into Postman and use it as a service definition.

To import a .proto file, do the following:

1. Go to the Service definition tab and select Import a .proto file.

2. You can drag and drop a .proto file from your local system or select Choose a File to open the file explorer.

3. Once you have selected the file, select Next. This takes you to the Import as API interface.

4. Give your new API a name, add a version name, and select Import as API.

This will create a new protobuf API from the .proto file and use it in the request as a service definition.

You can also import the .proto file as an update to an existing API. While on the Import as API interface, you can select an API from the list of available APIs in the workspace and add the .proto file as a new version. You can also replace it with an existing version by selecting an existing version from the list.

Instead of importing a .proto file from your local system, you can also fetch a .proto file from a URL by entering the URL into the import interface instead of selecting Choose a File.

Postman supports importing of multi-file schemas. You can import .proto files containing import directives referring to other files.

Storing a .proto file in your working directory

To foster collaboration on .proto files and ensure consistent file paths across team members, you can use the Postman working directory. By storing .proto files in the working directory, you and your team can share and collaborate on service definitions without needing to manually re-import files for each user. When a .proto file is imported from the working directory, it ensures that shared requests or collections referencing the file will work across everyone's system, provided that all team members have the respective .proto file in their configured working directory. This setup is useful when collaborating in shared workspaces or when using Newman for automated testing.

On macOS and Linux, you can find the default working directory at ~/Postman/files. On Windows, you can find the default working directory at %userprofile%\Postman\files (File Explorer and Command Prompt) or ~/Postman/files (PowerShell).

Adding import paths

Sometimes, gRPC schemas can be divided into multiple .proto files. These .proto files are referred through import directives in a schema. Import directives containing absolute paths (for example, /Users/johndoe/projects/my-app/protos/enums/NumericEnum.proto) and relative paths (../enums/NumericEnum.proto) are automatically resolved by Postman and don't require any more configuration. If the import directives don't contain absolute or relative paths, you must add their parent directories.

Consider this example file structure:

In this example, root.proto has import directives that refer to other .proto files in the protos folder. These import directives could look something like this in the schema:

import "enums/NumericEnum.proto"
import "messages/EmptyMessage.proto"
import "messages/HelloResponse.proto"
import "messages/HelloRequest.proto"

In this scenario, you'll need to configure the parent directory of enums and messages (in other words, protos) as your import path in Postman. The added import path can look something like this: /Users/johndoe/projects/my-app/protos/. After you import a proto file, select the Import paths tab to configure import paths in a request.