HTTP Status codes confusion

Question

So, I am trying to display meaningful and accurate HTTP status codes and I'm getting confused even after going through the examples online. Here's my situation:

In the URL which accepts the query param:

@POST query
Sample URL: /putRecord?Name=A&Age=25&house=permanent

1. what status code do i return when one of the params is missing? (All 3 are mandatory) - from what I've read, I am guessing it is a 400: Bad request. But this seems too general. Is there a way for me to say that the query was malformed? Source: here
2. Assuming I validate the name for duplicates against the DB, if I get a duplicate, what status code do I return?

3. So, if there's a duplicate entry available already, I can't add the record. Do I display 304 (Not modified) or just the error code from 2? Clarification: For 3, another possibility is when I can't actually commit to the DB and I rollback(possibly). What status code will it be now?

   Thanks so much!

Answer 1

Ad 1. You can return, besides the code itself (400) also a short message with explanation. So, instead of returing "400 Bad Request" you could respond with "400 Query param name required" or something similar. This message is called "reason phrase" and is defined in 6.1 in RFC 2616 . Or, if you need more flexibility, you could return document with the explanation.

Ad 2. I would consider using 422 Unprocessable entity. From the RFC 4918 :

The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity, 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.

Ad 3. I would return 422, but it really depends whether this situation is considered an error in your logic, or is it a regular, expected situation.

Edit : As @War10ck suggested in the comment, HTTP 409 (in place of HTTP 422) might make sense as well.

---

Note on handling duplicates: it seems (correct me if I'm wrong) that you consider new entity being a duplicate if it's name is already in the database. If so, that you could maybe consider using a HTTP PUT instead of HTTP POST?

You could define the following resource:

HTTP PUT /record/:name

So, "name" would be a part of the URI. Then, in case there is a second PUT to the same resource (same "name"), it'd be elegant to respond with 409/422.

If you're using different key for unique constraint, modify the URI appropriately.

As a rule of thumb, POST is for situations where you can have multiple instances of a given resource, ie

HTTP POST /log  ;; Because we have many logs

And PUT for situations where each resource is unique:

HTTP PUT /person/:name (or /person/:tax-number if :name isn't unique)

Also, note that I've renamed your resource from "putRecord" to "record" - PUT is a HTTP method, no reason to have it in URI as well.