plug_rest v0.6.2 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

  resource "/pages/:page", PageResource
end

The resource/2 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.

Options

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"

Because the router builds on Plug’s own Router, you can add additional plugs into the pipeline. See the documentation for Plug.Router for more information.

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} = read_path_params(conn)

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 read_path_params/1 will return:

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

If we make a request to “/hello/value/extra” then read_path_params/1 will return:

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

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.