gRPC | Faustine Docs

For a gRPC API, Faustine turns every unary method of your services into an operation that takes and returns JSON. The service definitions come from server reflection, from .proto files you upload or from the repository.

Get started

Create the API from APIs > New API with gRPC as the API type. See Create a gRPC API.

Where the definitions come from

The Schema source step of the wizard has three options.

Option	What Faustine reads
Fetch via server reflection	The descriptors of your live server, over `grpc.reflection.v1`, or `v1alpha` when the server does not implement `v1`. You set up the first connection in the same step. This is the most reliable source.
Upload .proto files or a zip	One or more `.proto` files, or a zip with the whole proto tree so that imports resolve. Up to 5 MB. The well-known types under `google/protobuf` are included.
Analyze the repository	The `.proto` files in the repository and the files they import.

The proto is the source of truth. When a repository is connected, the analysis also reads the handlers to write summaries and hints. Reflection and .proto files win over code.

Operations

Each unary method becomes one operation. Streaming methods (client, server and bidirectional) are not served. The analysis lists them in its findings.

The key is derived from the method name, with the same vocabulary REST operations use:

Method	Key
`DealService.ListDeals`	`deals.list`
`DealService.GetDeal`	`deals.get`
`DealService.CreateDeal`	`deals.create`
`DealService.DeleteDeal`	`deals.delete`
`DealService.ArchiveDeal`	`deals.archive`
`HealthService.Check`	`health.check`

A method whose name starts with a reading verb, such as List, Get, Find or Search, is a read. The others are writes.

Request and response messages follow the proto3 JSON mapping. The agent sends and receives JSON with lowerCamelCase field names, and well-known types such as Timestamp and Duration are written as strings.

Connections

A gRPC connection has an address and a transport.

Field	Description
Address (host:port)	Where the server listens, with no scheme or path, such as `api.nimbuscrm.example:443`.
TLS	On by default.
Allow plaintext (insecure)	Shown when TLS is off. For development servers only: credentials travel unencrypted, and the server has to accept h2c.
Mutual TLS	Optional. Client certificate (PEM) and Client key (PEM), which go together, and CA bundle (PEM, optional) for a server certificate that a public authority did not sign.

The gateway makes each call with a deadline of 30 seconds.

Credentials

A gRPC API receives its credential as metadata. For API key / static token, Send as is fixed to gRPC metadata and you enter the Metadata key. A token from a bot user, an OAuth client or a sign-in script travels as lower-case metadata entries, such as authorization. With Pass-through, the caller's X-Upstream-Authorization value is forwarded as authorization. See Authentication.

Status codes

The gateway reports a gRPC status to the agent as the HTTP status of the call.

gRPC status	HTTP status
`OK`	200
`INVALID_ARGUMENT`, `OUT_OF_RANGE`, `FAILED_PRECONDITION`	400
`UNAUTHENTICATED`	401
`PERMISSION_DENIED`	403
`NOT_FOUND`	404
`ALREADY_EXISTS`, `ABORTED`	409
`RESOURCE_EXHAUSTED`	429
`CANCELLED`	499
`UNIMPLEMENTED`	501
`UNAVAILABLE`	502
`DEADLINE_EXCEEDED`	504

Testing

Test connection on a gRPC connection also reports whether server reflection answers. If reflection is turned off on the server, upload the .proto files instead.

After the analysis, a connection is tested with a read operation, as for any API.

Next steps

Create a gRPC API: the steps of the wizard for each source.
Operations: review the operations and their flags.
Add a connection: add the addresses of your other environments.
API frameworks: the frameworks the wizard lists for gRPC.