plug_rest v0.14.0 PlugRest.Router View Source

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/4 macro accepts a request of format "/pages/VALUE" and dispatches it to PageResource, which must be a Plug module.

See PlugRest.Resource for information on how to write a Plug module that implements REST semantics.

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"]}

Link to this section Summary

Types

Options for a Router macro

A URL path

A Plug Module

Options for the Plug

Link to this section Types

Link to this type

options()

View Source
options() :: list()

Options for a Router macro

A URL path

A Plug Module

Link to this type

plug_opts()

View Source
plug_opts() :: any()

Options for the Plug

Link to this section Functions

Link to this macro

resource(path, plug, plug_opts \\ [], options \\ [])

View Source (macro)
resource(path(), plug(), plug_opts(), options()) :: Macro.t()

Main API to define resource routes.

It accepts an expression representing the path, a Plug module, the options for the plug, and options for the macro.

Examples

resource "/path", PlugModule, plug_options, macro_options

Options

resource/4 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.
  • :private - a map of private data to merge into the connection
  • :assigns - a map of data to merge into the connection

The macro accepts options that it will pass to the Plug:

resource "/pages/:page", PageResource, [p: 1]

You can restrict the resource to only match requests for a specific host. If the plug doesn't take any options, pass an empty list as the third argument to the macro:

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