# Protobuf contracts

How Polyester keeps its typed APIs, REST endpoints, SDKs, and public schemas aligned from shared Protobuf contracts.

Polyester defines its public typed application APIs using Protobuf. These contracts describe services, methods, messages, field types, validation rules, and compatibility boundaries.

ConnectRPC clients consume the contracts directly. Polyester's official SDKs build on the same definitions, providing language-specific types and higher-level integration helpers.

[Browse the public Protobuf contracts](https://github.com/Fabric-Labs/polyester-proto)

## One contract, multiple interfaces

Polyester developed custom contract-generation tooling to produce a developer-friendly REST surface from the same Protobuf definitions used by ConnectRPC.

The tooling generates REST request and response models, conversions to and from the canonical Protobuf messages, validation boundaries, and OpenAPI descriptions. Both interfaces then invoke the same business capabilities instead of maintaining separate handwritten API models.

| Derived surface   | What comes from the contracts                                                        |
| ----------------- | ------------------------------------------------------------------------------------ |
| ConnectRPC        | Typed procedure paths, messages, validation, and JSON or binary Protobuf encoding    |
| REST              | Generated JSON models, canonical message conversion, validation, and OpenAPI schemas |
| Official SDKs     | Language-specific types and clients for the published services                       |
| API documentation | Public methods, fields, constraints, and schema references                           |

This contract-first pipeline keeps shared operations, field semantics, and validation rules aligned as the API evolves. A contract change flows through generated clients, REST adapters, schemas, and documentation rather than requiring the same shape to be maintained independently in each layer.

> **Public contracts only**
>
> The published Protobuf bundle contains the public API contract. Internal and administrative services are not included in public descriptors, documentation, OpenAPI schemas, or SDK generation.

## Intentional interface differences

Contract alignment does not mean that REST and ConnectRPC have identical wire representations. Polyester adapts some fields to make each interface natural for its users:

- REST commonly uses decimal strings, readable JSON, and text-form public IDs.
- ConnectRPC can use binary Protobuf or ProtoJSON and preserves Protobuf integer representations.
- Authentication, headers, status codes, and error envelopes follow the selected interface.
- Some capabilities may be available through only one interface.

These differences are explicit mappings around the shared contract, not separate business models. Review [Public IDs](https://testnet.polyester.com/docs/developer-docs/shared-concepts/public-ids) and [Scaled integers](https://testnet.polyester.com/docs/developer-docs/connectrpc/scaled-integers) before translating payloads between interfaces.

## Using the contracts directly

Developers are not limited to the official SDK languages. The published contracts can be used to generate compatible Protobuf types and Connect clients for other supported ecosystems.

When integrating directly:

- generate code only from the published contract bundle
- follow each field's documented validation, unit, and scale
- preserve unknown fields when your Protobuf runtime supports them
- treat package versions as API compatibility boundaries
- use the interface-specific guides for authentication and wire-format behavior.

Continue with [ConnectRPC getting started](https://testnet.polyester.com/docs/developer-docs/connectrpc/getting-started) for typed HTTP calls or [REST getting started](https://testnet.polyester.com/docs/developer-docs/rest/getting-started) for the generated JSON interface.