Vapor GitHub

You're viewing documentation for an older version. View the latest version

Basic Routing#

Routing is one of the most critical parts of a web framework. The router decides which requests get which responses.

Vapor has a plethora of functionality for routing including route builders, groups, and collections. In this section, we will look at the basics of routing.

Register#

The most basic route includes a method, path, and closure.

drop.get("welcome") { request in
    return "Hello"
}

The standard HTTP methods are available including get, post, put, patch, delete, and options.

drop.post("form") { request in
    return "Submitted with a POST request"
}

Nesting#

To nest paths (adding /s in the URL), simply add commas.

drop.get("foo", "bar", "baz") { request in
    return "You requested /foo/bar/baz"
}

You can also use /, but commas are often easier to type and work better with type safe route parameters.

Alternate#

An alternate syntax that accepts a Method as the first parameter is also available.

drop.add(.trace, "welcome") { request in
    return "Hello"
}

This may be useful if you want to register routes dynamically or use a less common method.

Request#

Each route closure is given a single Request. This contains all of the data associated with the request that led to your route closure being called.

Response Representable#

A route closure can return in three ways:

  • Response

  • ResponseRepresentable

  • throw

Response#

A custom Response can be returned.

drop.get("vapor") { request in
    return Response(redirect: "http://vapor.codes")
}

This is useful for creating special responses like redirects. It is also useful for cases where you want to add cookies or other items to the response.

Response Representable#

As you have seen in the previous examples, Strings can be returned in route closures. This is because they conform to ResponseRepresentable

A lot of types in Vapor conform to this protocol by default:

drop.get("json") { request in
    var json = JSON()
    try json.set("number", 123)
    try json.set("text", "unicorns")
    try json.set("bool", false)
    return json
}

Throwing#

If you are unable to return a response, you may throw any object that conforms to Error. Vapor comes with a default error enum Abort.

drop.get("404") { request in
    throw Abort(.notFound)
}

You can customize the message of these errors by using Abort

drop.get("error") { request in
    throw Abort(.badRequest, reason: "Sorry 😱")
}

These errors are caught by default in the ErrorMiddleware where they are turned into a JSON response like the following.

{
    error: true,
    message: "<the message>"
}

If you want to override this behavior, remove the ErrorMiddleware (key: "error") from the Droplet’s middleware and add your own.

Fallback#

Fallback routes allow you to match multiple layers of nesting slashes.

app.get("anything", "*") { request in
    return "Matches anything after /anything"
}

For example, the above route matches all of the following and more:

  • /anything

  • /anything/foo

  • /anything/foo/bar

  • /anything/foo/bar/baz

  • …