Problem Details for HTTP APIs (RFC7807)
Extensible implementation of RFC7807 — Problem Details for HTTP APIs
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
Date: Sun, 01 Nov 2020 22:28:42 GMT
"title": "File resource doesn't exist",
"detail": "Cannot upload file content to a non-existent file.",
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
In addition the package provides basic support for
Servant.Server.RFC7807 module documentation
for more information and usage examples.
Why would I want to use this?
There are many ways common ways how API error responses are structured in HTTP
APIs. Using this one has few advantages:
It is standardised in RFC7807 — Problem Details for HTTP APIs
. This can be leveraged in terms of
documentation, libraries built with it in mind, and not heaving to reinvent
something that people have put a lot of thought into.
Gives you a nice template that is still flexible and extensible. This is
important if we are retrofitting it into an existing API.
Documented by default. The
type field is a URL, used correctly can allow us
to prevent a lot of issues by linking errors with their documentation.
Increasing level of detail. We have
finally custom fields. This way we can progressively add more information
allowing users to easily debug issues.
Proxy friendly. When proxies are involved, so called layering, it is quite
easy to loose the original status code. This can also happen with some HTTP
libraries that do not retain the status code.
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:
Your needs are in direct conflict with the RFC7807 — Problem Details for
HTTP APIs standard. For example, fields
that are defined by the standard are reserved in your system or protocol
When RFC7807 messages cannot easily be retrofitted into your API and you need
to preserve backward compatibility.
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
Servant.Server.RFC7807 in section Usage Examples