What should be the API Response for already performed or unneeded operations

Question

What response (code + content) should I return when my JsonAPI is requested to perform some operation that has already been done or does not make sense ?

Example : suppose I want to request an article publication. The article draft is updated through a specific endpoint (irrelevant here), and there is a specific endpoint one for publication (whose response we are interested in)

4 different scenarii, I need to figure out what type of response to send each time :

1. Publication had never been requested, and the article has all publication mandatory information, it makes sense to request publication so I'm returning a 202 accepted response with the article resource including the "publication requested at" attribute

2. A successful publication publication request was already sent/acknowledged, and no one had time to review it in between. What should I return ?

3. A previous publication request was reviewed by someone and accepted (the article is now published). The API receives once more a publication request to this article that was already published, it doesn't make sense, what should I return ?

4. The article does not have all mandatory information filled and someones make a publication request. I must inform the user his request was not granted because of errors. I was thinking for this one I could return the list of validation errors. Sounds fair ?

Answer 1

Your first two bullets...

• Publication had never been requested, and the article has all publication mandatory information, it makes sense to request publication so I'm returning a 202 accepted response with the article resource including the "publication requested at" attribute
• A successful publication publication request was already sent/acknowledged, and no one had time to review it in between. What should I return ?

...are amenable to 202 Accepted:

202 Accepted: The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.

Your third bullet:

• A previous publication request was reviewed by someone and accepted (the article is now published). The API receives once more a publication request to this article that was already published, it doesn't make sense, what should I return ?

I would probably use a 303 redirect here:

303 See other: The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), the client should presume that the server has received the data and should issue a redirect with a separate GET message.

But you could also consider a 308 permanent redirect:

308 Permanent Redirect (RFC 7538): The request and all future requests should be repeated using another URI. 307 and 308 parallel the behaviors of 302 and 301, but do not allow the HTTP method to change. So, for example, submitting a form to a permanently redirected resource may continue smoothly.

But I'd lean towards the 303.

And your last bullet:

• The article does not have all mandatory information filled and someones make a publication request. I must inform the user his request was not granted because of errors. I was thinking for this one I could return the list of validation errors. Sounds fair ?

This is a standard "bad client request" (4xx) with errors:

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

Just make sure you don't expose the implementation details of your service when you enumerate the errors in your response.

Remember:

• 2xx responses indicate success
• 3xx responses indicate redirection
• 4xx responses indicate a failure on the part of the client
• 5xx responses indicate a failure on the part of the application servicing the request

Source: List of HTTP status codes