Good User Experience and API Success both require clarity in API Responses

It’s been quite a while that I worked closely with some financial institutions, few banking sandboxes from Nordic and North European countries, and many other API enthusiasts building APIs for their product extensibility and overall interoperability.

It is true that while user experience and related research determine the future success of a product, how otherwise one could ensure smooth user experience in real world software other than focusing on exhaustive scenarios that might unfold in user experience. And those include encompassing all the error scenarios and corresponding messages to the end users.

When RFC7807 Spec is first read, no relevance can be found for end-users or UX designers. But in the end, it is the responsibility of a development team building the API integration and backend to ensure that experience is not compromised.

One of the interesting standards I came across few months ago ( I had to be honest here, I also knew before that only standard HTTP response codes of 2xx success ,3xx redirect, 4xx client error, and 5xx server error were enough) was RFC 7807 and it answered all the possible questions on how a truly intuitive User Experience is still possible despite when connecting external APIs and infrastructures might be going unstable and their Beta phase.

Needless to say, if your product is not doing the intended function for the end-users, it is unfit to be in market. However in problem/error scenarios it matters a lot when you honestly communicate with users to comprehend what exactly happened, what could be the exact cause, if users should try again sooner or later, or otherwise should the product reengage to the user when it is available.

For example (not from RFC 7807 perspective), if UI issues an aggregated API call, whose sub-components have timed out to fetch, you have two options ( at first place API aggregation should have been sensible always): 1. either communicate the partial object state to the UI or 2. fail the call completely. But there cannot be both ways!

Similar ways, if a POST API makes a difference between when to return 200 (success) or 201 (created new object successfully), it becomes a lot easier for the UI to determine if its request calls influence to your APIs. Also it stays in close touch with what is happening beneath the scene.

How should a DELETE API then behave ? Maybe 204 as success code, though certain criticism of 204 you may read here

Fair enough, that was bit of playing devil’s advocate while trying to describe the distress one may feel with the choice of picking an error code to return and missing to describe the problem to the calling method. But what if a problem is communicated back to user with a type of JSON schema, called Problem JSON type in RFC7807 Standard Spec?

While going thru RFC7807 adoption, I could not be more happier when I found Zalando’s team in github mentioning it and developing it for proper responsive error messages in their backend implementation

Following the example given in RFC 7087 Spec itself, how credible it would be to have such error message of problem ( ‘problem is a type’) JSON as:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
"name": "age",
"reason": "must be a positive integer"
},
{
"name": "color",
"reason": "must be 'green', 'red' or 'blue'"}
]
}

Which part of error above you did not understand ? And if you did, will it be any difficult to tell to end user? If above was a “400-Bad Request” kind of error case, but still you wanted to educate the user on what went wrong in his request, how much of error code to error message mapping and other DevOps overheads you would save? Maybe it is better to suggest all API developers to begin embarking the journey of piloting your API error messages as per RFC7807 now on. It will definitely be worth the effort spent in right direction of building your API backbones or true interoperability and integrations.

PS: The only criticism of RFC7807 one may have ( if you are SOAP literate ), that this might look like imposing HATEOS restrictions, but again it is both responsibility and available alternative to have some standards in place for API error responses!