# HttpRouter
[![Build Status](https://img.shields.io/travis/slogsdon/elixir-http-router.svg?style=flat)](https://travis-ci.org/slogsdon/elixir-http-router)
[![Coverage Status](https://img.shields.io/coveralls/slogsdon/elixir-http-router.svg?style=flat)](https://coveralls.io/r/slogsdon/elixir-http-router)
[![Hex.pm Version](http://img.shields.io/hexpm/v/http_router.svg?style=flat)](https://hex.pm/packages/http_router)
[![Inline docs](http://inch-ci.org/github/slogsdon/elixir-http-router.svg?branch=master)](http://inch-ci.org/github/slogsdon/elixir-http-router)
> HTTP Router with various macros to assist in
> developing your application and organizing
> your code
## Installation
Add the following line to your dependency list
in your `mix.exs` file, and run `mix deps.get`:
```elixir
{:http_router, "~> 0.0.1"}
```
Also, be sure to add `:http_router` to the list
of applications on which your web application
depends (the default looks something like
`applications: [:logger]`) in your `mix.exs`
file.
Be sure to have [Plug][plug] in your dependency
list as well as this is essentially a
reimagination of the `Plug.Router` module, and
as such, it still make use of a large portion
of the Plug library.
## Usage
To get the benefits that this package has to
offer, it is necessary to use the `HttpRouter`
module in one of your modules that you wish to
act as the router for your web application.
Similar to `Plug.Router`, we can start with a
simple module:
```elixir
defmodule MyRouter do
use HttpRouter
end
```
That was easy, huh? Now, this module still needs a
few calls to the below macros, but this depends on
how your application needs to be structured.
### The Macros
Check out this convoluted example:
```elixir
defmodule MyRouter 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
```
`get/3`, `post/3`, `put/3`, `patch/3`, `delete/3`,
`options/2`, and `any/3` are already built-in as
described. `resource` 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` will need to be created outright. Will
allow requests to contained endpoints when version
exists in either `Accepts` header or URL (which ever
is defined in app config).
Extra routes will need to be added for `*.json`,
`*.xml`, etc. requests for optionally specifying
desired content type without the use of the
`Accepts` header. These should match
parsing/rendering abilities of your application.
## Configuration
TBD.
## License
HttpRouter is released under the MIT License.
See [LICENSE](license) for details.
[plug]: https://github.com/elixir-lang/plug
[license]: https://github.com/slogsdon/elixir-http-router/blob/master/LICENSE