Code as schema: how we generate the Increase API

Increase treats application code - not a separately maintained API specification - as the source of truth for its API. Engineers define each endpoint’s HTTP method, path, parameters, response, and documentation through a shared framework. The framework enforces conventions and types, parses requests into strongly typed objects, and offers reusable helpers for tasks such as loading a database record from a resource ID. By shifting checks into the framework, it can catch errors early, provide suggestions for misspelled parameters, verify permissions and environments, and report multiple request problems together. The goal is to keep endpoint implementations thin and make consistency easier to maintain as the API grows to hundreds of endpoints.

The same code definitions are converted through Ruby reflection into OpenAPI 3.1, which then feeds the API reference, language-specific SDKs, and Postman collections. Reusing resource definitions produces shared schema references, while the generator can express features such as discriminators and enum descriptions that are awkward or unavailable in standard OpenAPI. Centralized generation also lets Increase choose consistent representations for ambiguous schema features and prevents published documentation from drifting from actual behavior. The overall approach runs from code to validated schema, then from schema to portable specification and developer tools. Increase says it has not open-sourced the framework because some parts are coupled to its own codebase and ORM, but argues that the model lets a small team sustain a high-quality developer experience.