apipie-rails

If your API actions are defined in a module instead of directly in the controller, you can load the Apipie DSL into that module by extending it with Apipie::DSL::Concern.

To allow a module to be reused across different controllers with different values, use apipie_concern_subst(:key => "value") within the controller before including the module. This performs substitutions in paths, descriptions, and parameter names.

Default Substitutions:

• :controller_path: The value of controller.controller_path (e.g., api/users). Note: This is only used if you are not using the api! keyword.
• :resource_id: The Apipie identifier of the resource (e.g., users). This can be set via the resource_id method.

# users_module.rb
module UsersModule
  extend Apipie::DSL::Concern

  api :GET, '/:controller_path', 'List :resource_id'
  def index
    # ...
  end

  api! 'Show a :resource'
  def show
    # ...
  end

  api :POST, '/:resource_id', "Create a :resource"
  param :concern, Hash, :required => true
    param :name, String, 'Name of a :resource'
    param :resource_type, ['standard','vip']
  end
  def create
    # ...
  end

  api :GET, '/:resource_id/:custom_subst'
  def custom
    # ...
  end
end

# users_controller.rb
class UsersController < ApplicationController

  resource_description { resource_id 'customers' }

  apipie_concern_subst(:custom_subst => 'custom', :resource => 'customer')
  include UsersModule
end

To avoid repeating parameter definitions across multiple actions (like create and update), use parameter groups.

1. Define a group using def_param_group :name do ... end in a controller.
2. Apply it to an action using param_group :name.
3. To reference a group from a different controller, use param_group :name, OtherController.

Example:

# In a controller
def_param_group :address do
  param :street, String
  param :zip, String
end

api :POST, "/users", "Create"
param_group :address
def create
  # ...
end

# v1/users_controller.rb
def_param_group :address do
  param :street, String
  param :number, Integer
  param :zip, String
end

def_param_group :user do
  param :user, Hash do
    param :name, String, "Name of the user"
    param_group :address
  end
end

api :POST, "/users", "Create a user"
param_group :user
def create
  # ...
end

# v2/users_controller.rb
api :POST, "/users", "Create a user"
param_group :user, V1::UsersController
def create
  # ...
end

Apipie supports versioning at the resource and method levels using the api_version DSL keyword.

• Resource level: Use api_versions "1", "2" inside a resource_description block to assign multiple versions to a resource.
• Method level: Use api_version "1" before a specific method to override the resource's versioning.
• Inheritance: Version settings on a parent controller are inherited by children.
• Deprecation: Use :deprecated => true in the api definition to flag routes.

Apipie generates versioned paths like /apipie/1/users/index. If no version is specified, it uses Apipie.configuration.default_version (defaults to "1.0").

When querying or referencing resources, use the format "version#resource#method".

resource_description do
  api_versions "1", "2"
end

api :GET, "/api/users/", "List: users"

api_version "1"
def index
  # ...
end

api :GET, "/api/users/", "List: users", :deprecated => true

In CRUD operations, parameters often have different requirements depending on the action (e.g., required: true for create, but required: false for update).

By setting :action_aware => true in a param definition within a def_param_group, Apipie automatically adjusts the required status based on the HTTP method:

• POST/Create: required becomes true.
• PUT/Update: required becomes false.

You can also explicitly force an evaluation mode using the :as option (e.g., :as => :create).

Example:

def_param_group :user do
  param :user, Hash, :action_aware => true do
    param :name, String, :required => true
  end
end

api :POST, "/users", "Create"
param_group :user
def create
  # ...
end

api :PUT, "/users/:id", "Update"
param_group :user
def update
  # ...
end

def_param_group :user do
  param :user, Hash, :action_aware => true do
    param :name, String, :required => true
  end
end

api :POST, "/users", "Create a user"
param_group :user
def create
  # ...
end

api :PUT, "/users/admin", "Create an admin"
param_group :user, :as => :create
def create_admin
  # ...
end

api :PUT, "/users/:id", "Update a user"
param_group :user
def update
  # ...
end

When reusing a param_group for both inputs and outputs, use the :only_in option to specify whether a parameter belongs to the request or the response. This prevents fields like :id (which is in the response but not the request body) from causing validation errors.

Options:

• :only_in => :response: Parameter is included in the response but ignored in requests.
• :only_in => :request: Parameter is included in the request but ignored in the response.

def_param_group :user do
  param :user, Hash, :desc => "User info", :required => true, :action_aware => true do
    param :id, Integer, :only_in => :response
    param :requested_id, Integer, :only_in => :request
    param_group :credentials
    param :membership, ["standard","premium"], :desc => "User membership", :allow_nil => false
  end
end

api :GET, "/users/:id", "Get user record"
returns :user, :desc => "the requested record"
error :code => 404, :desc => "no user with the specified id"