Jammies

A JSON API-compliant HTTP error handler for Play! 2.4.x

Jammies is an implementation of the Play Framework's HttpErrorHandler interface that handles errors by sending JSON responses. It's a small project, but it has a lot going for it:

Jammies is easy to use! (see below)
Jammies is backed by a large unit test suite.
Jammies has a permissive MIT license that allows it to be used almost anywhere.
Jammies aims to be fully compliant with the JSON API standard (http://jsonapi.org), insofar as errors go.

Why "Jammies"?

"Jammies" is a silly name that was picked without much forethought. It's a really half-hearted attempt at a back-ronym:

JSON API(-compliant)
Mitigation (of)
Errors (for RESTful)
Services

Yes, it does quite a good job of spelling out JAMES, but that's a boring name for a project. The name "Jammies" is also somewhat relatable to this library's general use case: having some good Jammies (pajamas) can help you REST easier. Yeah, it's corny, but at least it's memorable in some respect.

Usage

Installation

Jammies is supported on the Play Framework version 2.4.x and above. To start using it, you'll simply need to add two configuration entries to your project.

The first entry goes in your project's build.sbt file, inside the libraryDependencies section. This tells Play! to download Jammies and make it available for use in your application. Add it like so:

libraryDependencies ++= Seq(
    // (... some other dependencies, maybe ...)
    "com.mattgawarecki.play" % "jammies" % "latest.stable"
    // (... some more dependencies, maybe ...)
)

NOTE: latest.stable in the example above indicates that the latest stable version of Jammies should be downloaded. If you want to use a different version, please feel free to change this value. For a list of all versions, visit Jammies at the Central Maven Repository.

The second entry should be added to your application's conf/application.conf file. This entry tells Play! to use Jammies whenever an error occurs:

play.http.errorHandler = "com.mattgawarecki.play.jammies.JsonApiHttpErrorHandler"

Configuration

By default, Jammies tries to expose the details of any error it handles in the detail field of the response it generates. You can configure this setting manually by adding the following entry to your project's conf/application.conf file:

jammies.showDetailedErrors=true

NOTE: To protect potentially-sensitive information about internal application behavior and/or architecture, error details will not be shown by default if the application is running in "production" mode (e.g., running from a deployed binary generated by activator dist). The above configuration entry overrides this behavior, however.

Creating your own responses

You can also use Jammies to create error responses manually in your application's code. This is great for situations in which Play! has accepted the incoming request on a low level, but you detect an error condition on your own.

There are basically three ways to create an error response:

Call any one of the following "convenient" pre-defined response methods from the JsonApiErrorResponse class:
- HTTP 400 (Bad Request)
  - badRequest()
  - badRequest(detail)
- HTTP 403 (Forbidden)
  - forbidden()
  - forbidden(detail)
- HTTP 404 (Not Found)
  - notFound()
  - notFound(detail)
- HTTP 500 (Internal Server Error)
  - internalServerError()
  - internalServerError(detail)
Call JsonApiErrorResponse.status(status, title, detail) to build a "simple" custom response
Manually instantiate a JsonApiError object and wrap it using JsonApiErrorResponse.status(JsonApiError) to create a comprehensive response with any field supported by the JSON API error message specification.

Known Issues

I18N support is non-existent. All response text is in American English.
Intrinsic (comment-based) documentation is very sparse.
JsonApiHttpErrorHandler is not covered by unit tests. Dependencies on static classes inside the Play Framework have made this difficult to fix, but test coverage is planned.

mattgawarecki/play-jammies