An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
doc
lib
test
.gitignore
.travis.yml
LICENSE
README.md
mix.exs
mix.lock

README.md

Explode

Build Status Hex.pm

An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications.

This project is heavily influenced by Hapi's Boom module [https://github.com/hapijs/boom]

Installation

defp deps do
  [{:explode, "~> 1.0.0"}]
end

Usage

Turns

conn
|> put_resp_content_type("application/json")
|> send_resp(:unauthorized, "{\"statusCode\":403,\"error\":\"Forbidden\",\"message\":\"You are not authorized to view this resource\"}")
|> halt

into

conn |> Explode.with(403, "You are not authorized to view this resource")

# or

conn |> Explode.forbidden("You are not authorized to view this resource")

Error Responses

Explode sets the status code of the response and normalizes errors into a single structure:

{
    "statusCode": 403,
    "error": "Not Authorized",
    "message": "You are not authorized to view this resource"
}

JSON API

In order to be compliant with the JSON API spec (http://jsonapi.org/format/#errors), if the request headers in the conn object passed to Explode includes Accept of "application/vnd.api+json", then the error response will be formatted to match the JSON API Error Object spect (http://jsonapi.org/format/#errors). Additionally, the Content-Type header of the response will also be set to "application/vnd.api+json".

{		
    "errors" : [{		
        "status": 403,		
        "title":"Forbidden",		
        "detail":"You are not authorized to view this resource"		
    }]		
}

Ecto Changeset

Explode will also accept an Ecto.Changeset struct instead of a message. This allows a Pheonix application to directly hand a Changeset to Explode without having to do an traversal of errors.

changeset = %Ecto.Changeset{
  action: :insert, 
  types: %{},
  changes: %{first_name: "John", last_name: "Smith", password: "foo"},
  errors: [
    password: {"should be at least %{count} character(s)", [count: 5, validation: :length, min: 5]},
    email: {"can't be blank", [validation: :required]}],
  valid?: false,
  data: %User{}
}

Explode.with(conn, changeset)

will result in the following error response:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "`email` can't be blank, `password` should be at least 5 character(s)"
}