HttpRouter v0.0.8 → Overview → HttpRouter

HttpRouter

Summary
Macros

HttpRouter defines an alternate format for Plug.Router routing. Supports all HTTP methods that Plug.Router supports.

Routes are defined with the form:

method route [guard], handler, action

method is get, post, put, patch, or delete, each responsible for a single HTTP method. method can also be any, which will match on all HTTP methods. options is yet another option for method, but when using options, only a route path and the methods that route path supports are needed. handler is any valid Elixir module name, and action is any valid public function defined in the handler module.

get/3, post/3, put/3, patch/3, delete/3, options/2, and any/3 are already built-in as described. resource/2 exists but will need modifications to create everything as noted.

raw/4 allows for using custom HTTP methods, allowing your application to be HTTP spec compliant.

version/2 allows requests to contained endpoints when version exists in either Accept header or URL (which ever is defined in the app config).

Extra routes will be added for *.json, *.xml, etc. requests for optionally specifying desired content type without the use of the Accept header. These match parsing/rendering abilities of HttpRouter.

Example

defmodule Router do
  use HttpRouter

  # Define one of the versions of the API
  # with a simple version number "1"
  # or following semver "1.0.0"
  # or date of release "2014-09-06"
  version "1" do
    # Define your routes here
    get  "/",               Handlers.V1.Pages, :index
    get  "/pages",          Handlers.V1.Pages, :create
    post "/pages",          Handlers.V1.Pages, :create
    put  "/pages/:page_id" when id == 1,
                            Handlers.V1.Pages, :update_only_one
    get  "/pages/:page_id", Handlers.V1.Pages, :show

    # Auto-create a full set of routes for resources
    #
    resource :users,        Handlers.V1.User, arg: :user_id
    #
    # Generates:
    #
    # get     "/users",           Handlers.V1.User, :index
    # post    "/users",           Handlers.V1.User, :create
    # get     "/users/:user_id",  Handlers.V1.User, :show
    # put     "/users/:user_id",  Handlers.V1.User, :update
    # patch   "/users/:user_id",  Handlers.V1.User, :patch
    # delete  "/users/:user_id",  Handlers.V1.User, :delete
    #
    # options "/users",           "HEAD,GET,POST"
    # options "/users/:_user_id", "HEAD,GET,PUT,PATCH,DELETE"
  end

  # An updated version of the AP
  version "2" do
    get  "/",               Handlers.V2.Pages,  :index
    post "/pages",          Handlers.V2.Pages,  :create
    get  "/pages/:page_id", Handlers.V2.Pages,  :show
    put  "/pages/:page_id", Handlers.V2.Pages,  :update

    raw :trace, "/trace",   Handlers.V2.Tracer, :trace

    resource :users,        Handlers.V2.User
    resource :groups,       Handlers.V2.Group
  end
end

Summary↑

any(route, handler, action)	Macro for defining `ANY` routes
delete(route, handler, action)	Macro for defining `DELETE` routes
get(route, handler, action)	Macro for defining `GET` routes
options(route, allows)	Macro for defining `OPTIONS` routes
patch(route, handler, action)	Macro for defining `PATCH` routes
post(route, handler, action)	Macro for defining `POST` routes
put(route, handler, action)	Macro for defining `PUT` routes
raw(method, route, handler, action)	Macro for defining routes for custom HTTP methods
resource(resource, handler, opts \\ [])	Creates RESTful resource endpoints for a route/handler combination
version(version, list)	Macro for defining a version for a set of routes

Macros

any(route, handler, action)

(macro) # ↑

Specs:

any(term, binary | list, atom, atom) :: ast

Macro for defining ANY routes.

Arguments

route - String|List
handler - Atom
action - Atom

delete(route, handler, action)

(macro) # ↑

Specs:

delete(term, binary | list, atom, atom) :: ast

Macro for defining DELETE routes.

Arguments

route - String|List
handler - Atom
action - Atom

get(route, handler, action)

(macro) # ↑

Specs:

get(term, binary | list, atom, atom) :: ast

Macro for defining GET routes.

Arguments

route - String|List
handler - Atom
action - Atom

options(route, allows)

(macro) # ↑

Specs:

options(term, binary | list, binary) :: ast

Macro for defining OPTIONS routes.

Arguments

route - String|List
allows - String

patch(route, handler, action)

(macro) # ↑

Specs:

patch(term, binary | list, atom, atom) :: ast

Macro for defining PATCH routes.

Arguments

route - String|List
handler - Atom
action - Atom

post(route, handler, action)

(macro) # ↑

Specs:

post(term, binary | list, atom, atom) :: ast

Macro for defining POST routes.

Arguments

route - String|List
handler - Atom
action - Atom

put(route, handler, action)

(macro) # ↑

Specs:

put(term, binary | list, atom, atom) :: ast

Macro for defining PUT routes.

Arguments

route - String|List
handler - Atom
action - Atom

raw(method, route, handler, action)

(macro) # ↑

Specs:

raw(term, atom, binary | list, atom, atom) :: ast

Macro for defining routes for custom HTTP methods.

Arguments

method - Atom
route - String|List
handler - Atom
action - Atom

resource(resource, handler, opts \\ [])

(macro) # ↑

Specs:

resource(term, atom, atom, Keyword.t) :: [ast]

Creates RESTful resource endpoints for a route/handler combination.

Example

resource :users, Handlers.User

expands to

get,     "/users",      Handlers.User, :index
post,    "/users",      Handlers.User, :create
get,     "/users/:id",  Handlers.User, :show
put,     "/users/:id",  Handlers.User, :update
patch,   "/users/:id",  Handlers.User, :patch
delete,  "/users/:id",  Handlers.User, :delete

options, "/users",      "HEAD,GET,POST"
options, "/users/:_id", "HEAD,GET,PUT,PATCH,DELETE"

version(version, list)

(macro) # ↑

Specs:

version(term, binary, any) :: ast | [ast]

Macro for defining a version for a set of routes.

Arguments

version - String