What Does a Controller Do?

A controller is the middleman between models and views. It makes the model data available to the view so it can display that data to the user, and it saves or updates user data to the model.

The controller is the C in MVC. After the router has determined which controller to use for a request, the controller is responsible for making sense of the request and producing the appropriate output. Luckily, Amber::Controller::Base does most of the groundwork for you and uses smart conventions to make this as straightforward as possible.

For most conventional RESTful applications, the controller will receive the request (this is invisible to you as the developer), fetch or save data from a model and use a view to create HTML output. If your controller needs to do things a little differently, that's not a problem, this is just the most common way for a controller to work.

Controller Naming Convention

When defining your routes you specify the controller that the route will match to

get "/", ApiController, :index

In the snippet above, ApiController is the name of the controller ./src/controller/api_controller.cr

Methods and Actions

A controller is a Crystal class which inherits from ApplicationControllerand has methods just like any other class. When your application receives a request, the routing will determine which controller and action to run, then Amber creates an instance of that controller and runs the method with the same name as the action.

Controllers are defined as such:

class ApiController < ApplicationController
def index
@client = Client.new

As an example, if a user goes to api/index in your application to add a new client, Amber will create an instance of ApiController and call it's index method

Actions Conventions

While actions can be named anything we like, there are conventions for action names which you should adhere whenever possible. We went over these in the Routing Guide, but we’ll take another quick look here.




renders a list of all items of the given resource type


renders an individual item by id


renders a form for creating a new item


receives parameters for one new item and saves it in a persistent store


retrieves an individual item by id and displays it in a form for editing


receives parameters for one edited item and saves it to a persistent store


receives an id for an item to be deleted and deletes it from a persistent store