Status for POST responses

[elbrujohalcon]

---

Status responses for POST

For POST /entities, the server is expected to respond with:

• 200 OK if the entity was created and it's returned in the response body
• 204 OK if the entity was created but it is not returned in the response body
• 400 Bad Request if the request body can't be parsed
• 401 Unauthorized if the caller can't be authenticated
• 403 Forbidden if the caller can't create the entity
• 404 Not Found if the url is invalid
• 422 Unprocessable Entity if the request body can be parsed but it contain invalid parameters (also used when the entity to be created already exists)

Examples

Good

Use this section to show proper examples of API design, like:

• POST /examples -d { ▶️ 400
• POST /examples -d {} ▶️ 422
• POST /examples -d {"id": 1} ▶️ 204
• POST /examples -d {"id": 1} ▶️ 422 in the body it should explain that it's duplicated

Bad

Use this section to show bad examples of API design, like:

• POST /examples -d { ▶️ 422
• POST /examples -d {} ▶️ 400
• POST /examples -d {"id": 1} ▶️ 200 without body
• POST /examples -d {"id": 1} ▶️ 409

Reasoning

We would be following the lead of the HTTP RFC and understanding duplicated entity as a regular validation.
References:

• HTTP Status Codes RFC
• HTTP Extensions for 422

---