An introduction to RFC 7807 | Representing Problem Details in HTTP APIs

Almost all APIs have a way of reporting problems and errors, making it easier for the API consumer to understand that something went wrong, and what went wrong. How to do that depends on the API style, API technology, and the specific API design. In all these cases, this part of API design needs to be addressed as part of the overall design work.

For APIs using the Hypertext Transfer Protocol (HTTP), some minimal reporting can be done using HTTP’s status codes. HTTP status codes are interesting because they already provide a certain level of details, with ~60 different codes reporting a variety of conditions which are defined by HTTP itself and a few other specifications.

However, while these codes are useful because they can be supported in generic HTTP tooling, there often is the need to be more specific, for example by providing a more detailed problem type, or by providing information about a specific invocation of the API. In these cases, APIs may want to supplement HTTP’s out-of-the-box mechanism and its status codes, and the question is how to best do this in an API design.

One possibility is to design it yourself as an API designer, but that takes time and effort on the designer side as well for all consumers who have to understand that particular design. Luckily, there’s a standard out there, and this standard is IETF RFC 7807 (published in 2016).

By using RFC 7807, API designers save the effort of designing their own way of exposing API problem details, and API consumers can apply their understanding of that standard to all APIs where it’s used. So if that standard fits the APIs needs, using it is a win-win value proposition.

RFC 7807 is a simple specification. It defines a JSON format, and an associated media type, with the JSON format defining an object that has five optional members for describing a problem detail:

type: A URI reference that identifies the problem type. Ideally, the URI should resolve to human-readable information describing the type, but that’s not necessary. The problem type provides information that’s more specific than the HTTP status code itself.
title: A human-readable description of the problem type, meaning that it should always be the same for the same type.
status: This reflects the HTTP status code and is a convenient way to make problem details self-contained. That way they can be interpreted outside of the context of the HTTP interaction in which they were provided.
detail: A human-readable description of the problem instance, explaining why the problem occurred in this specific case.
instance: A URI reference that identifies the problem instance. Ideally, the URI should resolve to information describing the problem instance, but that’s not necessary.

RFC 7807 simple extension model

RFC 7807 has a simple extension model: APIs are free to add any other members to the problem details object, so all members other than the five ones listed above are extensions. However, there is no namespacing or registry, meaning that finding out what an extension means is outside the scope of RFC 7807.

And this is all there is to RFC 7807. Consider using this format in your API designs, sparing you the effort of designing your own mechanism, and making it easier for others to understand your way of exposing problem details.

If you’re interested in more information, patterns, and anti-patterns for using RFC 7807, and some examples of how to use them in API designs, please consider watching the following video. In it, Mike Amundsen talks about how he used to handle problems in his APIs, how he discovered and started using RFC 7807, and how he is using it in the API designs that he now creates.