Explode

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 Phoenix 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)"
}

Bring your own JSON encoder

Explode by default with use Poison as the JSON encoding library. If you want to change that out, you can do so in config.exs

config(:explode, :json_library, Jason)