Code as Schema: Designing Strict APIs for Autonomous AI Agents and Client SDKs
Increase detailed its internal framework that derives OpenAPI 3.1 specifications directly from typed application code. By moving validations to build time and generating machine-readable schemas, a single engineer maintains hundreds of consistent, agent-ready endpoints.
Why it matters
Adopt code-first schema generation to prevent documentation drift and give coding agents deterministic interfaces with explicit parameter descriptions.
TL;DR
- 01Define endpoint interfaces in strictly typed backend code rather than maintaining standalone YAML specifications.
- 02Catch missing field documentation and type mismatches at CI build time using static analyzers.
- 03Export rich OpenAPI 3.1 schemas with discriminators and enum descriptions to prevent agent hallucinations during tool calls.
Key facts
- OpenAPI Target
- OpenAPI 3.1
- Language / Typing
- Ruby with Sorbet static type checking
- DX Team Size
- 1 engineer managing hundreds of endpoints
Eliminating Schema Drift at the Source
Maintaining hundreds of API endpoints manually creates severe friction for both human developers and autonomous AI agents. Rather than hand-authoring OpenAPI schemas or treating documentation as a separate deliverable, Increase treats executable application code as the authoritative source of truth. Each API endpoint inherits from an abstract method class that declares its HTTP verb, path, query parameters, and response attributes.
class AccountCreate < APISchema::AbstractAPIMethod
string :name, documentation: AccountResource.attributes.name.documentation
enum :funding,
documentation: AccountResource.attributes.funding.documentation,
cases: AccountResource.attributes.funding.cases
def operate
account = Model::Account.create!(name: params.name, funding: params.funding)
AccountResource.from_model(account)
end
endBuild-Time Guarantees and Automatic Model Hydration
The framework enforces documentation and parameter conventions before runtime. Omitting documentation strings on attributes or endpoint parameters causes Sorbet build-time type checking to fail. Parameter abstractions such as resource_id automatically look up and hydrate underlying database entities (Model::Account), passing typed objects straight into the handler. Typo detection, environment verification (such as detecting production versus sandbox IDs), and permission checks execute before controller logic runs, aggregating parse-time issues into a single unified error response.
Generating Rich OpenAPI 3.1 for Agents and SDKs
Reflection translates the Ruby definitions into an OpenAPI 3.1 document. Reusable resources are mapped into reusable $ref components, preventing code generators from creating duplicate models. Advanced features such as polymorphic discriminator mappings and vendor extensions (like x-enum-descriptions) are emitted systematically. This machine-readable specification directly feeds agent tool schemas, typed client libraries, Postman collections, and reference documentation without manual intervention.
Try it in 2 minutes
class AccountResource < APISchema::AbstractResource
string :id, documentation: "The Account identifier"
string :name, documentation: "The name of the Account"
enum :funding, documentation: "The type of the Account", cases: {
deposits: "A depository account such as checking or savings"
}
timestamp :created_at, documentation: "When the Account was created"
endruby
✓ When to use
- Building public developer platforms that require synchronized SDKs, docs, and Agent tool interfaces.
- Teams suffering from constant drift between controller behavior and outdated Swagger specifications.
✕ When NOT to use
- Rapid prototyping of microservices where contracts fluctuate hourly across unstable prototypes.
- Simple internal APIs where client SDK generation and external agent tooling are unnecessary.
What to do today
- Audit existing internal API schemas for missing parameter descriptions and enum value explanations.
- Evaluate build-time static type checks in your framework to enforce endpoint documentation requirements.
- Export unified OpenAPI 3.1 specs to feed Model Context Protocol (MCP) server definitions and agent tool configurations.
What the community says
“I wrote some thoughts on the workflow we use to publish our API documentation and related artifacts. I'm curious if others are doing similar or if there are other ways to do this.”