CODEWITHSUNDEEP
resthttpresponseapi-design
Kayla Kirzinger
Kayla Kirzinger

Reputation: 11

Suggested HTTP status code for specific API scenario?

We currently have an API that is following a less than ideal process, however due to business need cannot be deprecated or changed at this time. As such, I'd like to update the HTTP status code to more accurately reflect the error and I can't settle on one that makes sense for the scenario.

The endpoint is a GET and returns an array of entities. The ID for each entity is supposed to be a GUID string, however due to some faulty conversion data in the backend system there are integer IDs mixed in for certain requests. The API currently validates these IDs and sends a 500 response with no data if the IDs are not all GUIDs. We've had issues where our devs have been confused by the 500 so I'd like to find a more explicit response.

422 Unprocessable Entity kind of makes sense to me but based on RFC 4918 it looks to be more for formatting of the response.

If we did return only the GUID IDs I could see sending a 206 Partial.

Thoughts?

Upvotes: 1

Views: 230

Answers (2)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

Suggested HTTP status code for specific API scenario?

Keep in mind that status codes belong to the "transport documents over a network" domain; they are meta data in a standardized form so that general purpose components can recognize the semantics and act.

If you are using a GET, then presumably the IDs are encoded into the URI (the message-body of a request doesn't have any defined semantics when the method is GET). If the data is encoded into the URI, then it is part of the resource identifier.

If the resource identifier is ill formed, and you cannot provide a representation for the resource in question, the standard status-code to use is 404

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

Broadly, you are indicating to the client that there is a problem with the request and that the problematic part of the request is the target-uri. Normally, we would include in the message-body of the response more context specific information.

422 Unprocessable Entity ... looks to be more for formatting of the response.

422, like all 4xx status-codes, describes a problem in the request -- specifically that there is a semantic problem with the message-body of the request. This one is clearly appropriate to use with requests that include a message-body, including POST, PUT, PATCH and so on; it's not obviously appropriate for GET.

Upvotes: 0

trolley813
trolley813

Reputation: 932

I think that the "plain" 400 Bad Request should be enough (and the details should be expressed in the response body instead).

From Wikipedia:

400 Bad Request
The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).

The "malformed request syntax" part suits your case perfectly (since sending integers instead of strings (GUIDs) does not comply to the request schema and subsequently its syntax).

So, your API should return a response like this:

{"message": "Error processing element at index 8: a string GUID expected, integer '13' found"}

Update: If indeed only the GUIDs were sent, just return 200. The 206 code is for very different purpose (e.g. multithreaded downloading), when only a part of the (usually binary) response was delivered. In your case, the returned response is complete, even it contains only the GUIDs.

Upvotes: 1

Related Questions