Notes on RESTful API Design

This is a list of return codes in relation to a RESTful API design.

Some of the operations can have more than one outcome, so you need to decide on which one you find the most appropriate for your use case.

</td> </table>

Operation	HTTP Method	Status Code On Success	Notes
Create	POST	201 Created	When the object is created immediately
		202 Accepted	When the object is accepted but not created immediately</td</tr>
		400 Bad Request	If the submitted data are malformed
		404 Not Found	If referenced objects do not exist
		409 Conflict	If you handle that the same object cannot be created more than once
		422 Unprocessable Content	If submitted data are validated and validation fails
Read	GET	200 OK	When the object requested in included in the response
		404 Not Found	If referenced object/objects do not exist
Update	PUT	200 OK	When the updated object is returned as part of the response
		204 No Content	When the updated object is not returned as part of the response
		400 Bad request	If the submitted data are malformed
		404 Not Found	If referenced object/objects do not exist
		409 Conflict	If you handle that the object cannot be updated inconsistently
	PATCH	200 OK	When the updated object is returned as part of the response
		204 No Content	When the updated object is not returned as part of the response
		400 Bad Request	If the submitted data are malformed
		404 Not Found	If referenced object/objects do not exist
Delete	DELETE	200 OK	When an object changes status to deleted or similar (soft delete) and is returned as part of the response
		202 Accepted	When an object changes status to deleted or similar and is deleted a part of a garbage collection process or similar
		204 No Content	When an object is deleted immediately and the object is not returned
		404 Not Found	If referenced object do not exist

Status Code On Error	Notes
401 Unauthorized	If you receive a unauthenticated request, to a resource requiring authentication
403 Forbidden	If you receive a authenticated but unauthorized request, to a resource requiring authorization
405 Method not allowed	If you receive a HTTP method not supported
429 Too Many Requests	If you support rate limiting and set limit is reached
500 Internal Server Error	For you unhandled errors and errors server side

HTTP Method	Idempotent	Can become Idempotent
POST	No	Yes
PUT	Yes
PATCH	No
GET	Yes
HEAD	Yes
DELETE	Yes
OPTIONS	Yes

## Resources and References - [MDN: 200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200) - [MDN: 201 Created](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/201) - [MDN: 202 Accepted](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/202) - [MDN: 204 No Content](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/204) - [MDN: 400 Bad Request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400) - [MDN: 401 Unauthorized](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401) - [MDN: 403 Forbidden](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/403) - [MDN: 404 Not Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404) - [MDN: 405 Method not allowed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/405) - [MDN: 409 Conflict](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/409) - [MDN: 429 Too many requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429) - [MDN: 500 Server Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/500) - [MDN: 502 Bad Gateway](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/502) - [MDN: 503 Service Unavailable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503) - [MDN: 504 Gateway Timeout](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/504)