Base

GitHub

Base class for API definitions.

Created via API.define. Configure resources, types, enums, adapters, and exports. Each API is mounted at a unique path.

Example: Define an API

Apiwork::API.define '/api/v1' do
  key_format :camel

  resources :invoices do
    resources :items
  end
end

Class Methods

.adapter

.adapter(name = nil, &block)

GitHub

Sets or configures the adapter for this API.

Without arguments, returns the adapter instance. With a block, configures the current adapter. Without a name, the built-in :standard adapter is used.

Custom adapters must be registered via Adapter.register and referenced by their adapter_name.

Parameters

Name	Type	Default	Description
name	Symbol, nil	nil	A registered adapter name matching adapter_name in the adapter class.

Returns

Adapter::Base, void — the adapter instance when called without block

Yields Configuration

See also

• Adapter.register

Example: Configure the default :standard adapter

adapter do
  pagination do
    default_size 25
    max_size 100
  end
end

Example: Use a registered custom adapter

adapter :jsonapi

Example: Use and configure a custom adapter

adapter :jsonapi do
  pagination do
    strategy :cursor
  end
end

---

.base_path

.base_path

GitHub

The base path for this API.

Returns

String

---

.concern

.concern(name, &block)

GitHub

Defines a reusable concern for resources.

Concerns are reusable blocks of resource configuration that can be included in multiple resources via the concerns option.

Parameters

Name	Type	Default	Description
name	Symbol		The concern name.

Returns

void

Yields Resource

Example: instance_eval style

concern :archivable do
  member do
    post :archive
    post :unarchive
  end
end

resources :posts, concerns: [:archivable]

Example: yield style

concern :archivable do |resource|
  resource.member do |member|
    member.post :archive
    member.post :unarchive
  end
end

resources :posts, concerns: [:archivable]

---

.enum

.enum(name, deprecated: false, description: nil, example: nil, values: nil)

GitHub

Defines a reusable enumeration type.

Parameters

Name	Type	Default	Description
name	Symbol		The enum name.
values	Array<String>, nil	nil	The allowed values.
description	String, nil	nil	The description. Metadata included in exports.
example	String, nil	nil	The example. Metadata included in exports.
deprecated	Boolean	false	Whether deprecated. Metadata included in exports.

Returns

void

Example

enum :status, values: %w[draft sent paid]

---

.export

.export(name, &block)

GitHub

Enables an export for this API.

Parameters

Name	Type	Default	Description
name	Symbol		The registered export name. Built-in: :openapi, :typescript, :zod.

Returns

void

Yields Configuration

Example

export :openapi
export :typescript do
  endpoint do
    mode :always
  end
end

---

.fragment

.fragment(name, &block)

GitHub

Defines a fragment type for composition.

Fragments are only available for merging into other types and never appear as standalone types. Use fragments to define reusable field groups.

Parameters

Name	Type	Default	Description
name	Symbol		The fragment name.

Returns

void

Yields API::Object

Example: Reusable timestamps

fragment :timestamps do
  datetime :created_at
  datetime :updated_at
end

object :invoice do
  merge :timestamps
  string :number
end

---

.info

.info(&block)

GitHub

The info for this API.

Returns

Info, nil

Yields Info

Example: instance_eval style

info do
  title 'My API'
  version '1.0.0'
end

Example: yield style

info do |info|
  info.title 'My API'
  info.version '1.0.0'
end

---

.key_format

.key_format(format = nil)

GitHub

Configures key transformation for this API.

Transforms JSON keys in request bodies, response bodies, and query parameters. Incoming requests are normalized to underscore internally, so controllers always receive params[:user_name] regardless of format.

With :camel, user_name becomes userName. With :pascal, user_name becomes UserName. With :kebab, user_name becomes user-name.

Parameters

Name	Type	Default	Description
format	Symbol<:camel, :kebab, :keep, :pascal, :underscore>, nil	nil	The key format. Default is :keep.

Returns

Symbol, nil

Example: camelCase keys

key_format :camel

# Client sends: { "userName": "alice" }
# Controller receives: params[:user_name]
# Response: { "userName": "alice", "createdAt": "2024-01-01" }

---

.object

.object(name, deprecated: false, description: nil, example: nil, &block)

GitHub

Defines a reusable object type.

Parameters

Name	Type	Default	Description
name	Symbol		The object name.
deprecated	Boolean	false	Whether deprecated. Metadata included in exports.
description	String, nil	nil	The description. Metadata included in exports.
example	Object, nil	nil	The example. Metadata included in exports.

Returns

void

Yields API::Object

Example

object :item do
  string :description
  decimal :amount
end

---

.path_format

.path_format(format = nil)

GitHub

Configures URL path transformation for this API.

Transforms URL path segments: base path, resource paths, action paths, and explicit path: options. Path parameters like :id and :user_id are not transformed. Controllers and params remain underscore internally.

With :kebab, /api/user_profiles/:id becomes /api/user-profiles/:id. With :pascal, /api/user_profiles/:id becomes /api/UserProfiles/:id.

Parameters

Name	Type	Default	Description
format	Symbol<:camel, :kebab, :keep, :pascal, :underscore>, nil	nil	The path format. Default is :keep.

Returns

Symbol, nil

Example: kebab-case paths

path_format :kebab

resources :user_profiles
# URL: /user-profiles/:id
# Controller: UserProfilesController
# Params: params[:user_profile]

---

.raises

.raises(*error_code_keys)

GitHub

API-wide error codes.

Included in generated specs (OpenAPI, etc.) as possible error responses.

Parameters

Name	Type	Default	Description
error_code_keys	Array<Symbol>		The registered error code keys.

Returns

Array<Symbol>

Example

raises :unauthorized, :forbidden, :not_found
api_class.raises # => [:unauthorized, :forbidden, :not_found]

---

.resource

.resource(name, concerns: nil, constraints: nil, contract: nil, controller: nil, defaults: nil, except: nil, only: nil, param: nil, path: nil, &block)

GitHub

Defines a singular resource (no index action, no :id in URL).

Useful for resources where only one instance exists, like user profile or application settings.

Parameters

Name	Type	Default	Description
name	Symbol		The resource name (singular).
concerns	Array<Symbol>, nil	nil	The concerns to include.
constraints	Hash, Proc, nil	nil	The route constraints (regex, lambdas).
contract	String, nil	nil	The custom contract path.
controller	String, nil	nil	The custom controller path.
defaults	Hash, nil	nil	The default parameters for routes.
except	Array<Symbol>, nil	nil	The CRUD actions to exclude.
only	Array<Symbol>, nil	nil	The CRUD actions to include.
param	Symbol, nil	nil	The custom parameter name for ID.
path	String, nil	nil	The custom URL path segment.

Returns

void

Yields Resource

Example: instance_eval style

resource :profile do
  resources :settings
end

Example: yield style

resource :profile do |resource|
  resource.resources :settings
end

---

.resources

.resources(name, concerns: nil, constraints: nil, contract: nil, controller: nil, defaults: nil, except: nil, only: nil, param: nil, path: nil, &block)

GitHub

Defines a RESTful resource with standard CRUD actions.

This is the main method for declaring API endpoints. Creates routes for index, show, create, update, destroy actions. Nested resources and custom actions can be defined in the block.

Parameters

Name	Type	Default	Description
name	Symbol		The resource name (plural).
concerns	Array<Symbol>, nil	nil	The concerns to include.
constraints	Hash, Proc, nil	nil	The route constraints (regex, lambdas).
contract	String, nil	nil	The custom contract path.
controller	String, nil	nil	The custom controller path.
defaults	Hash, nil	nil	The default parameters for routes.
except	Array<Symbol>, nil	nil	The CRUD actions to exclude.
only	Array<Symbol>, nil	nil	The CRUD actions to include.
param	Symbol, nil	nil	The custom parameter name for ID.
path	String, nil	nil	The custom URL path segment.

Returns

void

Yields Resource

Example: instance_eval style

resources :invoices do
  member { post :archive }
  resources :items
end

Example: yield style

resources :invoices do |resource|
  resource.member { |member| member.post :archive }
  resource.resources :items
end

---

.union

.union(name, deprecated: false, description: nil, discriminator: nil, example: nil, &block)

GitHub

Defines a discriminated union type.

Parameters

Name	Type	Default	Description
name	Symbol		The union name.
deprecated	Boolean	false	Whether deprecated. Metadata included in exports.
description	String, nil	nil	The description. Metadata included in exports.
discriminator	Symbol, nil	nil	The discriminator field name.
example	Object, nil	nil	The example. Metadata included in exports.

Returns

void

Yields API::Union

Example

union :payment_method, discriminator: :type do
  variant tag: 'card' do
    object do
      string :last_four
    end
  end
end

---

.with_options

.with_options(options = {}, &block)

GitHub

Applies options to all nested resource definitions.

Useful for applying common configuration to a group of resources. Accepts the same options as #resources: only, except, defaults, constraints, controller, param, path.

Parameters

Name	Type	Default	Description
options	Hash	{}	The options to apply to nested resources.

Returns

void

Yields Resource

Example: instance_eval style

with_options only: [:index, :show] do
  resources :reports
  resources :analytics
end

Example: yield style

with_options only: [:index, :show] do |resource|
  resource.resources :reports
  resource.resources :analytics
end

---