Resource

GitHub

Block context for defining API resources and routes.

Resource provides the DSL available inside resources and resource blocks. Methods include nested resources, custom actions, and concerns.

Example: Defining resources with actions

Apiwork::API.define '/api/v1' do
  resources :invoices do
    member do
      post :send
      get :preview
    end

    collection do
      get :search
    end

    resources :items
  end
end

Instance Methods

#collection

#collection(&block)

GitHub

Block for defining collection actions.

Collection routes don't include 🆔 /invoices/action

Returns

void

Yields Resource

Example: instance_eval style

collection do
  get :search
  post :bulk_create
end

Example: yield style

collection do |collection|
  collection.get :search
  collection.post :bulk_create
end

---

#concern

#concern(concern_name, callable = nil, &block)

GitHub

Defines a reusable concern.

Parameters

Name	Type	Default	Description
concern_name	Symbol		The concern name.
callable	Proc, nil	nil	Optional callable instead of block.

Returns

void

Yields Resource

Example: instance_eval style

concern :commentable do
  resources :comments
end

resources :posts, concerns: [:commentable]

Example: yield style

concern :commentable do |resource|
  resource.resources :comments
end

resources :posts, concerns: [:commentable]

---

#concerns

#concerns(*concern_names, **options)

GitHub

Includes previously defined concerns.

Parameters

Name	Type	Default	Description
concern_names	Array<Symbol>		The concern names to include.
options	Hash	{}	The options passed to the concern.

Returns

void

Example

resources :posts do
  concerns :commentable, :taggable
end

---

#delete

#delete(action_names, on: nil)

GitHub

Defines a DELETE action.

Parameters

Name	Type	Default	Description
action_names	Symbol, Array<Symbol>		The action name(s).
on	Symbol<:collection, :member>, nil	nil	The scope.

Returns

void

Example

member { delete :archive }

---

#get

#get(action_names, on: nil)

GitHub

Defines a GET action.

Parameters

Name	Type	Default	Description
action_names	Symbol, Array<Symbol>		The action name(s).
on	Symbol<:collection, :member>, nil	nil	The scope.

Returns

void

Example: Inside member block

member { get :preview }

Example: With on parameter

get :search, on: :collection

---

#member

#member(&block)

GitHub

Block for defining member actions (operate on :id).

Member routes include :id in the path: /invoices/:id/action

Returns

void

Yields Resource

Example: instance_eval style

member do
  post :send
  get :preview
end

Example: yield style

member do |member|
  member.post :send
  member.get :preview
end

---

#patch

#patch(action_names, on: nil)

GitHub

Defines a PATCH action.

Parameters

Name	Type	Default	Description
action_names	Symbol, Array<Symbol>		The action name(s).
on	Symbol<:collection, :member>, nil	nil	The scope.

Returns

void

Example

member { patch :mark_paid }

---

#post

#post(action_names, on: nil)

GitHub

Defines a POST action.

Parameters

Name	Type	Default	Description
action_names	Symbol, Array<Symbol>		The action name(s).
on	Symbol<:collection, :member>, nil	nil	The scope.

Returns

void

Example

member { post :send }

---

#put

#put(action_names, on: nil)

GitHub

Defines a PUT action.

Parameters

Name	Type	Default	Description
action_names	Symbol, Array<Symbol>		The action name(s).
on	Symbol<:collection, :member>, nil	nil	The scope.

Returns

void

Example

member { put :replace }

---

#resource

#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, no :id in URL).

Default actions: :show, :create, :update, :destroy.

Parameters

Name	Type	Default	Description
resource_name	Symbol		The resource name (singular).
concerns	Array<Symbol>, nil	nil	The concerns to include.
constraints	Hash, Proc, nil	nil	The route constraints.
contract	String, nil	nil	The custom contract path.
controller	String, nil	nil	The custom controller path.
defaults	Hash, nil	nil	The default route parameters.
except	Array<Symbol>, nil	nil	The actions to exclude.
only	Array<Symbol>, nil	nil	The CRUD actions to include.
param	Symbol, nil	nil	The custom ID parameter.
path	String, nil	nil	The custom URL 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(resource_name = nil, concerns: nil, constraints: nil, contract: nil, controller: nil, defaults: nil, except: nil, only: nil, param: nil, path: nil, &block)

GitHub

Defines a plural resource with standard CRUD actions.

Default actions: :index, :show, :create, :update, :destroy.

Parameters

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

Returns

Hash{Symbol => Resource}

Yields Resource

Example: instance_eval style

resources :invoices do
  member { get :preview }
  resources :items
end

Example: yield style

resources :invoices do |resource|
  resource.member { |member| member.get :preview }
  resource.resources :items
end

---

#with_options

#with_options(options = {}, &block)

GitHub

Applies options to all resources defined in the block.

Parameters

Name	Type	Default	Description
options	Hash	{}	The options to merge into 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

---