HttpRouter

v0.10.0

HttpRouter v0.10.0 HttpRouter

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

Macros

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) 
any(term, binary | list, atom, atom) :: ast

Macro for defining ANY routes.

Arguments

  • route - String|List
  • handler - Atom
  • action - Atom
delete(route, handler, action) 
delete(term, binary | list, atom, atom) :: ast

Macro for defining DELETE routes.

Arguments

  • route - String|List
  • handler - Atom
  • action - Atom
get(route, handler, action) 
get(term, binary | list, atom, atom) :: ast

Macro for defining GET routes.

Arguments

  • route - String|List
  • handler - Atom
  • action - Atom
options(route, allows) 
options(term, binary | list, binary) :: ast

Macro for defining OPTIONS routes.

Arguments

  • route - String|List
  • allows - String
patch(route, handler, action) 
patch(term, binary | list, atom, atom) :: ast

Macro for defining PATCH routes.

Arguments

  • route - String|List
  • handler - Atom
  • action - Atom
post(route, handler, action) 
post(term, binary | list, atom, atom) :: ast

Macro for defining POST routes.

Arguments

  • route - String|List
  • handler - Atom
  • action - Atom
put(route, handler, action) 
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) 
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 \\ []) 
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) 
version(term, binary, any) :: ast | [ast]

Macro for defining a version for a set of routes.

Arguments