RFC7807 Problem Details HTTP error – Guidelines and Best practices
Today in this article, we shall understand RFC7807 ProblemDetails HTTP Specification for representing HTTP status code and associated details and will also learn their specified guidelines and best practices to follow them correctly.
We will cover the below aspects in the article,
As we know there are specifications around HTTP status codes already which are used worldwide and are followed accordingly.
There are also RESTFul specifications that are language agnostic and are widely used across the developer community including .NET, JAVA, Python, Typescript, or Javascript-based framework.
However, Until the RFC7807 specification was released in 2016, there was no uniform format for the HTTP Error response representation.
RESTful – Resource is Prime
All REST principle and architecture style has a Resource at his heart.
These are an architectural style that defines a set of specifications to be used for creating API/Servies/Microservices.
Problem Statement:
No Uniform format for Error reponse for HTTP APIs.
Most languages were using standard HTTP status codes along with their implementation.
RESTFul API is language agnostic and it’s easy for each language to have its implementation of an error response including .NET, Python, Java, Typescript or Javascript, etc.
Most time HTTP status code does not require any further information to be transmitted. but there are cases when additional information is required to be sent as a response.
To understand more precisely, let’s take one example of HTTP Status code 500 Internal Server error.
For example, the client gets a very generic response from API in the format of HTTP status code and message error,
More precisely in JSON format most used format is as below,
Example:
{
Status: 500,
Message: "InternalServer Error"
}
- HTTP status codes aren’t always enough to communicate enough information about an error to be meaningful.
- The above HTTP 500 error is more generic and there could be 100 reasons for this error to occur.
- So in such cases, the client has not had many details for remediation from their side and they need to contact API developers.
Resolution – RFC7807 Problem Details released
Considering the same requirements new specifications were released in 2016.
The Internet Engineering Task Force (IETF) produced a specification in March 2016 that defines “problem details” as a mechanism to transport machine-readable details of failures in an HTTP response, avoiding the need to specify new error response formats for HTTP APIs.
References: https://datatracker.ietf.org/doc/html/rfc7807
A standard known as RFC7807, or “Problem Details for HTTP APIs,” establishes a consistent framework for expressing and conveying error and problem details in HTTP APIs.
RFC7807 was required because HTTP APIs lacked a standard error format. It was designed to give API answers in a uniform and standardized manner to communicate error information.
Prior to RFC7807, numerous ad hoc error types were used by different APIs, making it difficult for clients to understand and handle problems consistently across distinct APIs.
For API customers, the absence of standards resulted in confusion, ineffective error handling, and higher development effort.
By offering a clear structure for conveying error information in HTTP responses, RFC7807 seeks to alleviate these problems. The requirement includes a “Problem Details”
Prior to RFC7807, different APIs used various ad-hoc error formats, making it challenging for clients to interpret and handle errors consistently across different APIs. This lack of standardization led to confusion, inefficient error handling, and increased development efforts for API consumers.
RFC7807 aims to address these issues by providing a well-defined format for representing error information in HTTP responses. The standard specifies a “Problem Details” object, represented in JSON or XML, that contains the following key fields:
Define RFC7807 Problem Details and Its optional parameters
RFC7807 is a straightforward and developer-friendly specification.
It specifies a JSON format and a media type for documenting problem details, with the JSON format specifying an object with five optional members.
Please note that all the parameters are optional standard parameters and can be extended by the developers using their custom parameters.
The problem details structure is defined below,
{
"type": "",
"title": "",
"status":""
"detail": "",
"instance": "",
}
Please see the below details as specified by the specification,
Where,
- type: A URI reference that identifies the problem type that provides human-readable documentation for the problem type. The problem type provides information that’s more specific than the HTTP status code itself.
- title: It provides documentation for the problem type in a human-readable format. Except for the purposes of localization, it SHOULD NOT vary from one incidence of the problem to the next.
- status: For this occurrence of the problem, the origin server generated an HTTP status code.
- details: A human-readable explanation of the problem instance, explaining problem details in this specific case.
- instance: URI reference that identifies the problem instance. It may or may not yield further information if dereferenced.
Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://www.thecodebuzz.com/probs/account-balance-low",
"title": "You do not have enough balance.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/checking-account/msgs/bd",
"balance": 30, //Add your custom fields
"accounts": ["/account/checking-account/0012"] // add your custom fields
}
Problem Details Extension and security – Best practices
- Additional members may be added to the problem details object by problem type definitions.
Example: Above we have defined balance and accounts are extensions to the Problem details structure.
"balance": 30, //Add your custom fields "accounts": ["/account/checking-account/0012"] // add your custom fields
- Clients who are consuming problem information must disregard any extensions they are unfamiliar with; this permits problem types to develop and become more complex. In the future, you should include more details.
- It is appropriate to declare a new problem type when an HTTP API wants to define a response that signals an error state depending on the scenarios.
- The information supplied in the definition of a new problem category must be thoroughly examined. Similarly, when creating a problem — regardless of how it is serialized — the details provided must be evaluated. Leaking information that can be used to compromise the system, gaining access to the system, or violating the privacy of system users are all risks.
- Because this can disclose sensitive aspects of the server implementation, its data, and so on, generators offering links to occurrence information are urged to avoid making implementation details like a stack dump available over the HTTP interface.
- There are risks that conclude leaking information that can be exploited to compromise the system and the privacy of users of the system.
Technical exceptions Vs Business exceptions
In our last article on exception handling best practices, we learn how to differentiate between technical exceptions and business exceptions.
You should only expose the Business exceptions to the user without giving any technical details of the issue.
Problem details can be of great help here as they will help you define your business exception by hiding secretes or data.
Also, it helps you centralize business response handling bringing an efficient way of managing the exception.
References:
Do you have any comments or ideas or any better suggestions to share?
Please sound off your comments below.
Happy Coding !!
Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.
