Design

What is Guardrail?

Guardrail generates source code from OpenAPI / Swagger specifications with a focus on type safety and ergonomics in each target language.

Three goals

• Documentation — a single point of truth for the interface to a software system.
• Better servers — unexpected API changes surface as compiler errors via generated routing layers.
• Better clients — fewer binary dependencies via generated client libraries.

Single point of truth

HTTP is extremely flexible. Constraining it to the subset that expresses your service reduces the burden of handling the protocol to the core terms of the API. Focus on semantics once routing and validation are generated.

Hand-written routing hides security holes, misses best practices, and multiplies effort across languages. A static specification lets security and platform teams reason about attack surface without reconstructing it from implementations.

Unexpected API changes are compiler errors

Generated traits with unimplemented members mean new or changed parameters become compiler (or lint) errors. Saying a parameter is optional forces you to contend with that optionality in Handler methods. Unused warnings then point at tests that never learned about the change.

Separation of business logic

Implement a function with a well-defined set of inputs and outputs. Business logic lives as an implementation of an abstract class, so unit tests can cover routing and handlers independently.

API structure slip is impossible

Altering parameters changes the function interface. Response codes and bodies are members of an enumeration of valid choices — you cannot return a structure that violates the spec. An endpoint in the spec without an implementation is an error.

Fewer binary dependencies

Hand-written client libraries accumulate cruft: renamed parameters, hardcoded HTTP clients, retry policies from another era. Those dependencies then fight the rest of the tree. Generated clients keep the protocol honest and leave HTTP configuration to the application.