understanding REST Response and HTTP status code

Question

I wanted to know how I should respond in my REST API.

Valid Example:

http://blah.com/api/v1/dosomething/123

The above is a valid request and currently I have a HTTP Status of 200 with a JSON response

{
    "dosomething": {
        "status": "OK",
        "results": "123"
    }
}

Now my question is, if the parameter passed is not valid ( I'm expecting a string of whole numbers ), do I return a HTTP Response of 200 and pass the error status back in the JSON response or should I pass something like a HTTP 400 response ( Bad request ) and list the error / issue with the request in the JSON response?

Error Example:

http://blah.com/api/v1/dosomething/123a

JSON Response:

{
    "dosomething": {
        "status": "ERROR",
        "errors": [
            "Value passed: |123a| must be a integer."
        ]
    }
}

Again my question is should I pass a 200 or 400 HTTP status on the request where the parameter passed is not what I'm expecting? Or should this always be a 200 response as the request is working?

What is considered best practice?

Answer 1

Use 404. Always. 404. To do otherwise is to misunderstand the nature of a URI and a resource. If http://blah.com/api/v1/dosomething/ identified the resource, and 123a were merely a parameter to it, then other codes could make sense. But it doesn't: http://blah.com/api/v1/dosomething/123 identifies the resource. If no such resource exists, return 404 Not Found .

You might possess some implementation detail that handles both resources http://blah.com/api/v1/dosomething/123 and http://blah.com/api/v1/dosomething/123a , but it is not the resource. From Roy Fielding's dissertation :

"The resource is not the storage object. The resource is not a mechanism that the server uses to handle the storage object. The resource is a conceptual mapping -- the server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content. All of these implementation-specific issues are hidden behind the Web interface; their nature cannot be assumed by a client that only has access through the Web interface."

Answer 2

Edit by author: 422 is a wrong answer. I misunderstood initial question and gave invalid answer. Please see response by @fumanchu: https://stackoverflow.com/a/10955717/441250 . My answer below is wrong.

I'd suggest to use "422 Unprocessable Entity" and include failure information in the body of your response.

The 422 (Unprocessable Entity) status code means the server
understands the content type of the request entity (hence a
415(Unsupported Media Type) status code is inappropriate), and the
syntax of the request entity is correct (thus a 400 (Bad Request)
status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML
request body contains well-formed (ie, syntactically correct), but
semantically erroneous, XML instructions.

It's unacceptable to use "200 Ok" or any other status codes when dealing with errors.

PS List of status codes: http://www.iana.org/assignments/http-status-codes/http-status-codes.xml

Answer 3

HTTP 400 is used to signify a problem with the HTTP request itself (such as an invalid HTTP header). Although you are not receiving the parameters you expect, the request is still a valid HTTP request, so I would return a 200 response but include details of the missing parameter in your JSON.