plug_rest v0.9.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
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 tonil
, 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"