# gRPC

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**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) > **New API** with **gRPC** as the **API type**. See [Create a gRPC API](https://docs.faustine.ai/apis/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](https://docs.faustine.ai/apis/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](https://docs.faustine.ai/apis/create-a-grpc-api/): the steps of the wizard for each source.
- [Operations](https://docs.faustine.ai/apis/operations/): review the operations and their flags.
- [Add a connection](https://docs.faustine.ai/apis/add-a-connection/): add the addresses of your other environments.
- [API frameworks](https://docs.faustine.ai/technologies/api-frameworks/): the frameworks the wizard lists for gRPC.