plug_rest v0.8.0 PlugRest.Router

A DSL to supplement Plug Router with a resource-oriented routing algorithm.

It provides a macro to generate routes that dispatch to specific resource handlers. For example:

defmodule MyApp.Router do
  use PlugRest.Router

  plug :match
  plug :dispatch

  resource "/pages/:page", PageResource
end

The resource/3 macro accepts a request of format "/pages/VALUE" and dispatches it to the PageResource module, which must adopt the PlugRest.Resource behaviour by implementing one or more of the callbacks which describe the resource.

From Plug.Router:

Notice the router contains a plug pipeline and by default it requires two plugs: match and dispatch. match is responsible for finding a matching route which is then forwarded to dispatch. This means users can easily hook into the router mechanism and add behaviour before match, before dispatch or after both.

Routes

resource "/hello", HelloResource

The example above will route any requests for “/hello” to the HelloResource module.

A route can also specify parameters which will be available to the resource:

resource "/hello/:name", HelloResource

The value of the dynamic path segment can be read inside the HelloResource module:

%{"name" => name} = conn.params

Routes allow globbing, which will match the end of the route. The glob can be discarded:

# matches all routes starting with /hello
resource "/hello/*_rest", HelloResource

Or saved as a param for the resource to read:

# matches all routes starting with /hello and saves the rest
resource "/hello/*rest", HelloResource

If we make a request to “/hello/value” then conn.params will include:

%{"rest" => ["value"]}

A request to “/hello/value/extra” will populate conn.params with:

%{"rest" => ["value", "extra"]}

Options

The router accepts a list of options:

  • :known_methods - custom list of HTTP methods known by your server, for example: ["GET", "HEAD", "OPTIONS", "TRACE"]

This option will override the default list of methods that each Resource knows about (GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS). If a Resource implements the known_methods callback, that list always takes precedence over the default list.

Summary

Macros

Main API to define resource routes

Macros

resource(path, handler, options \\ [])

Specs

resource(term, String.t, atom, list) :: Macro.t

Main API to define resource routes.

It accepts an expression representing the path, the name of a module representing the resource, and a list of options.

Examples

resource "/pages/:page", PageResource, host: "host1.", state: true

Options

resource/3 accepts the following options

  • :host - the host which the route should match. Defaults to nil, meaning no host match, but can be a string like “example.com” or a string ending with “.”, like “subdomain.” for a subdomain match.

  • :state - the initial state of the resource.

The macro accepts an optional initial state for the resource. For example:

resource "/pages/:page", PageResource, state: %{option: true}

You can restrict the resource to only match requests for a specific host:

resource "/pages/:page", PageResource, host: "host1.example.com"