http-rfc7807: RFC7807 style response messages

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

RFC7807 — Problem Details for HTTP APIs style response messages.

See GitHub README for more information.


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.2.0.0
Change log ChangeLog.md
Dependencies aeson (>=1.4.1.0 && <2), base (>=4.12 && <5), http-media (>=0.7.1.3 && <1), http-types (>=0.12.2 && <1), servant (>=0.15 && <1), servant-server (>=0.15 && <1), text (>=1.2.3.0 && <2) [details]
License BSD-3-Clause
Copyright (c) 2020 Peter Trško
Author Peter Trško
Maintainer peter.trsko@gmail.com
Category Web, Servant
Home page https://github.com/trskop/http-rfc7807#readme
Bug tracker https://github.com/trskop/http-rfc7807/issues
Source repo head: git clone https://github.com/trskop/http-rfc7807
Uploaded by PeterTrsko at 2020-12-12T12:48:56Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for http-rfc7807-0.2.0.0

[back to package description]

Problem Details for HTTP APIs (RFC7807)

Extensible implementation of RFC7807 — Problem Details for HTTP APIs in Haskell.

RFC7807 defines HTTP API error responses that are quite informative. Very basic example of such message could look like:

HTTP/1.1 404 Not Found
Transfer-Encoding: chunked
Date: Sun, 01 Nov 2020 22:28:42 GMT
Server: Warp/3.3.13
Content-Type: application/problem+json;charset=utf-8
Content-Length: 251

{
  "type": "https://example.com/docs/error#upload-to-missing-file",
  "title": "File resource doesn't exist",
  "status": 404,
  "detail": "Cannot upload file content to a non-existent file.",
  "documentId": "ae095978-2f7c-47aa-84dd-220be55195a5"
}

Table of Contents

(Links work on GitHub, but not on Hackage.)

What does this package do?

This library provides a data type Rfc7807Error that represents such error responses. It is designed to be extensible and to allow alternative representation of user defined fields. See module Network.HTTP.RFC7807 for documentation.

In addition the package provides basic support for servant-server package . See Servant.Server.RFC7807 module documentation for more information and usage examples.

Why would I want to use this?

Oh my

There are many ways common ways how API error responses are structured in HTTP APIs. Using this one has few advantages:

There's an interesting article "REST API Error Handling - Problem Details Response by Guy Levin published on 23rd of May, 2018 " that compares various stiles of error responses AKA problem details responses.

When would I want to use something else?

This response structure may not serve your needs if it's clashing with your needs. Some examples of that:

Usage examples

General usage (not tied to Servant) is documented in module Network.HTTP.RFC7807 in section Usage Examples .

Basic usage with Servant (actually servant-server) is documented in module Servant.Server.RFC7807 in section Usage Examples .