Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pkinney/explode
An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications
https://github.com/pkinney/explode
Last synced: 3 months ago
JSON representation
An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications
- Host: GitHub
- URL: https://github.com/pkinney/explode
- Owner: pkinney
- License: mit
- Created: 2016-08-08T21:26:53.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-05-31T20:57:21.000Z (over 1 year ago)
- Last Synced: 2024-08-09T08:32:40.847Z (5 months ago)
- Language: Elixir
- Size: 160 KB
- Stars: 44
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications. (HTTP)
- fucking-awesome-elixir - explode - An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications. (HTTP)
- awesome-elixir - explode - An easy utility for responding with standard HTTP/JSON error payloads in Plug- and Phoenix-based applications. (HTTP)
README
# Explode
[](https://github.com/pkinney/explode/actions/workflows/ci.yaml)
[](https://hex.pm/packages/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
```elixir
defp deps do
[{:explode, "~> 1.0.0"}]
end
```
## Usage
Turns
```elixir
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
```elixir
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:
```json
{
"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"`.
```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.
```elixir
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:
```json
{
"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](https://github.com/devinus/poison) as the JSON encoding library. If you want to change that out, you can do so in `config.exs`
```elixir
config(:explode, :json_library, Jason)
```