Apiwork

Typed APIs for Rails.

Apiwork lets you define your API once and derive validation, serialization, querying, and typed exports from the same definition.

It integrates with Rails rather than replacing it. Controllers, ActiveRecord models, and application logic remain unchanged.

See https://apiwork.dev for full documentation.

Apiwork introduces an explicit, typed boundary to a Rails application.

From a single definition, it provides:

• Runtime request validation
• Response serialization
• Filtering, sorting, and pagination
• Nested writes
• OpenAPI specification
• Generated TypeScript and Zod types

The same structures that validate requests in production are used to generate client artifacts. There is no parallel schema layer.

A representation describes how a model appears through the API:

class InvoiceRepresentation < Apiwork::Representation::Base
  attribute :id
  attribute :number, writable: true, filterable: true, sortable: true
  attribute :status, filterable: true
  attribute :issued_on, writable: true, sortable: true

  belongs_to :customer, filterable: true
  has_many :lines, writable: true
end

Types and nullability are inferred from ActiveRecord metadata.

From this definition, Apiwork derives:

• Typed request contracts
• Response serializers
• Query parameters for filtering and sorting
• Offset or cursor-based pagination
• Nested write handling
• OpenAPI and client type exports

A minimal controller:

def index
  expose Invoice.all
end

def create
  expose Invoice.create(contract.body[:invoice])
end

contract.body contains validated parameters.
expose serializes the response according to the representation.

Filtering and sorting are declared on attributes and associations.

Example query parameters:

?filter[status][eq]=sent
?sort[issued_on]=desc

Operators are typed and validated. Generated client types reflect the same structure.

Representations are optional. Contracts can be defined independently of ActiveRecord for webhooks, external APIs, or custom request and response shapes.

Add to your Gemfile:

bundle add apiwork

Then run:

rails generate apiwork:install

Under active development.

MIT