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 contractsOne 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.
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 and 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 for typed HTTP calls or REST getting started for the generated JSON interface.
