

# Controllers

Controllers help you organize related functionality into a single place. They can also be used to create RESTful resources.

## Basic

A basic controller looks like the following:

    import Vapor
    import HTTP

    final class HelloController {
        func sayHello(_ req: Request) throws -> ResponseRepresentable {
            guard let name = req.data["name"]?.string else {
                throw Abort(.badRequest)
            }

            return "Hello, \(name)"
        }
    }

Simple controllers don't need to conform to any protocols. You are free to design them however you see fit.

### Registering

The only required structure is the signature of each method in the controller. In order to register this method into the router, it must have a signature like `(Request) throws -> ResponseRepresentable`. `Request` and `ResponseRepresentable` are made available by importing the `HTTP` module.

    import Vapor
    let drop = try Droplet()

    let hc = HelloController()
    drop.get("hello", handler: hc.sayHello)

Since the signature of our `sayHello` method matches the signature of the closure for the `drop.get` method, we can pass it directly.

### Type Safe

You can also use controller methods with type-safe routing.

    final class HelloController {
        ...

        func sayHelloAlternate(_ req: Request) -> ResponseRepresentable {
            let name: String = try req.parameters.next(String.self)
            return "Hello, \(name)"
        }
    }

We add a new method called `sayHelloAlternate` to the `HelloController` that fetches a `String` from the request's parameters.

    let hc = HelloController()
    drop.get("hello", String.parameter, handler: hc.sayHelloAlternate)

Since `drop.get` accepts a signature `(Request) throws -> ResponseRepresentable`, our method can now be used as the closure for this route.

Note

Read more about type safe routing in the Routing Parameters section.

## Resources

Controllers that conform to `ResourceRepresentable` can be easily registered into a router as a RESTful resource. Let's look at an example of a `UserController`.

    final class UserController {
        func index(_ req: Request) throws -> ResponseRepresentable {
            return try User.all().makeJSON()
        }

        func show(_ req: Request) throws -> ResponseRepresentable {
            let user = try req.parameters.next(User.self)
            return user
        }
    }

Here is a typical user controller with an `index` and `show` route. Indexing returns a JSON list of all users and showing returns a JSON representation of a single user.

We could register the controller like so:

    let users = UserController()
    drop.get("users", handler: users.index)
    drop.get("users", User.self, handler: users.show)

But `ResourceRepresentable` makes this standard RESTful structure easy.

    extension UserController: ResourceRepresentable {
        func makeResource() -> Resource<User> {
            return Resource(
                index: index,
                show: show
            )
        }
    }

Conforming `UserController` to `ResourceRepresentable` requires that the signatures of the `index` and `show` methods match what the `Resource<User>` is expecting.

Now that `UserController` conforms to `ResourceRepresentable`, registering the routes is easy.

    let users = UserController()
    drop.resource("users", users)

`drop.resource` will take care of registering only the routes that have been supplied by the call to `makeResource()`. In this case, only the `index` and `show` routes will be supplied.

### Actions

Below is a table describing all of the actions available.

Action | Method | Path | Note
--- | --- | --- | ---
index | GET | /users | Returns all users, optionally filtered by the request data.
store | POST | /users | Creates a new user from the request data.
show | GET | /users/:id | Returns the user with the ID supplied in the path.
replace | PUT | /users/:id | Updates the specified user, setting any fields not present in the request data to `nil`.
update | PATCH | /users/:id | Updates the specified user, only modifying fields present in the request data.
destroy | DELETE | /users/:id | Deletes the specified user.
clear | DELETE | /users | Deletes all users, optionally filtered by the request data.
create | GET | /users/create | Displays a form for creating a new user.
edit | GET | /users/:id/edit | Displays a form for editing the specified user.
aboutItem | OPTIONS | /users/:id | Meta action. Displays information about which actions are supported.
aboutMultiple | OPTIONS | /users | Meta action. Displays information about which actions are supported.

Note

The `aboutItem` and `aboutMultiple` meta actions are implemented automatically if not overridden.

Tip

The difference between `replace` and `update` is subtle but important: If a field does not exist in the request data (for example, the user's age is missing), `update` should simply not update that field where as `replace` should set it to `nil`. If required data is missing from a `replace` request, an error should be thrown.

## Folder

Controllers can go anywhere in your application, but they are most often stored in the `App/Controllers/` directory.

Tip

If you are building a large application, you may want to create your controllers in a separate module. This will allow you to perform unit tests on your controllers.