2

I'm looking at the spec of a REST API and the designers have the following response json body for error conditions...

{
    "status": "",
    "serviceSpecErrorCode": "",
    "userMessage": "",
    "devMessage": "",
    "moreInfo": ""
}

Where "status" is to be a copy of the HTTP response code (like 404 for example).

Is it bad practice to do this? Any reason/benefit to do this?

Edit 1: I should mention, this is a spec that is not implemented yet. The reason I'm asking is more for best design/practice since we can change this now before implementation.

Edit 2: Sorry, one more thing I should mention based on some answers... The "status" value will be same/identical as HTTP response code. They will never be different.

Improve this question

5 Answers 5

Reset to default
4

Short answer

It's redundant. It duplicates the information available in the HTTP status code itself, thereby bringing the possibility of disagreement between the two.

If included in the response payload, the status code should be only advisory and must be the same status code in the actual HTTP response.

Long answer

When returning problem details for a HTTP API, you may want to have a look at the RFC 7807:

This document defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.

According to such document, besides other elements, the problem details object can contain the HTTP status code:

  • status (number): The HTTP status code generated by the origin server for this occurrence of the problem.

The RFC also states the following:

The status member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly.

The status member duplicates the information available in the HTTP status code itself, thereby bringing the possibility of disagreement between the two. Their relative precedence is not clear, since a disagreement might indicate that (for example) an intermediary has modified the HTTP status code in transit (e.g., by a proxy or cache).

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

Thanks for the detailed response and RFC reference!
2

"A man with a watch knows what time it is. A man with two watches is never sure."

So as long as I can get the HTTP status I would ignore the status code from the response's body (but I will log it just in case), the rest of the fields can give you better hints about what's happening when the response is not the expected one.

Improve this answer

Comments

0

Any reason/benefit to do this?

URL patterns, request methods, status codes and response models differ from API to API and are only meant to confuse consumers of REST services. But, so they say, SOAP is bad, because it's XML and RPC, and nobody in their right mind would use those, amirite?

Just go with whatever they offer you.

[Why would they] do this?

It allows for more fine-grained status codes, so you can return a more specific status code which wouldn't fit in a registered HTTP status code (because of course there exists a specific scenario doesn't quite fit any of the existing ones), causing you to have to go and dive into their documentation and look up what particular status codes a service response can contain, and handle it accordingly.

They could've also decided to do this because they expect to have consumers of their services who don't know how to read the status code from an HTTP response in their particular programming language and/or framework.

Improve this answer

Comments

0

It's redundant.

HTTP APIs should use the HTTP status code that best fits the purpose. This code should be available to any client. If the codes differ it might be that the "status" code is something else, but as you point out it's to be just a copy.

There's no benefit and it leads to confusion. Client developers will start to depend on the "status" code, and you'll never be able to get rid of it.

Improve this answer

Comments

0

Looks like a very bad idea to me. They can certainly do this for codes up and including 400 level but how will they do this for 500 level codes? Many times they are sent when your application doesn't even know what's going on.

It certainly makes sense to design your own codes like 1, 2, 3, etc or anything else that can be more useful to clients of your application.

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.