phoenix_rest v0.2.1 PhoenixRest.Router

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

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

Edit web/web.ex and add the router:

def router do
  quote do
    use Phoenix.Router
    use PhoenixRest.Router
  end
end

Then use the resource macro in your router to match a path with a resource handler:

defmodule MyApp.Router do
  use HelloPhoenix.Web, :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.

See the PlugRest documentation for more details about defining a Resource.

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:

def to_html(%{params: params} = conn, state) do
  %{"name" => name} = params
  {"Hello #{name}!", conn, state}
end

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 any resource allows custom methods, you must define them using this option. For example:

use PhoenixRest.Router, known_methods: ["GET", "HEAD", "OPTIONS", "TRACE"]

Nota bene: if a resource is requested using an HTTP verb that is not in the list of known methods, Phoenix will raise a NoRouterError rather than return a 501 Not Implemented status code.

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, state: true

Options

resource/3 accepts the following options

  • :state - the initial state of the resource.