Endpoints should be based on resources, not on actions. The request method determines the action.
Use nouns (not verbs) in the path, since the request method already has the verb.
Limit levels/nesting to maximum
- https://jsonapi.org - A specification for building APIs in JSON
|Method||Route||Action||HTML||Description||Success Code||Failure Code||Request Body||Response Body|
|GET||index||List all users||200 OK||404 Not Found||✖||Resource list|
|GET||show||Get single user||200 OK||404 Not Found||✖||Resource|
|GET||new||✓||Render create form||200 OK||404 Not Found||✖||HTML|
|POST||create||Create new user||201 Created||400 Bad Request or 422 Unprocessable Entity if malformed, 409 Conflict if duplicate||Resource||Location header + status - see below|
|GET||edit||✓||Render edit form||200 OK||404 Not Found||✖||HTML|
|PUT||update||Update user, or create if it doesn't exist||200 OK or 204 No Content if updated, otherwise 201 Created||Resource||Optional|
|PATCH||update||Update user, partial||200 OK or 204 No Content||404 Not Found||Resource||Optional|
|DELETE||delete||Delete user||200 OK or 204 No Content||✖||Entity describing status or nothing|
- Use 204 No Content if the response has no body, otherwise 200 OK.
- 202 Accepted can be used if the operation is accepted but action is deferred.
Request has no body, response does.
Response should have "a Location header field that provides an identifier for the primary resource created and a representation that describes the status of the request while referring to the new resource(s)".
If the request is malformed (eg a missing parameter) you can use either 400 Bad Request or 422 Unprocessable Entity. See:
POST if the resource already exists (eg duplicate username or email)
- HTTP response code for POST when resource already exists - https://stackoverflow.com/questions/3825990/http-response-code-for-post-when-resource-already-exists
- What's a proper response status code to REST POST request when duplicate is found? - https://stackoverflow.com/questions/9414374/whats-a-proper-response-status-code-to-rest-post-request-when-duplicate-is-foun
- Which HTTP response code for "This email is already registered"? - https://stackoverflow.com/questions/9269040/which-http-response-code-for-this-email-is-already-registered
- 422 or 409 status code for existing email during signup - https://stackoverflow.com/questions/50946698/422-or-409-status-code-for-existing-email-during-signup
- HTTP Status Code for username already exists when registering new account - https://stackoverflow.com/questions/26587082/http-status-code-for-username-already-exists-when-registering-new-account
POST to a collection, PUT to a resource source
PUT creates a resource if it doesn't exist, or updates it if it does (UPSERT).
Return 404 if the resource does not exist.
According to https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#742-patch it should support UPSERT.
REST vs RPC
the RPC model makes it very simple and direct for programmers to write a procedure in one program and call it from another. This is one of the characteristics that makes RPC so popular, but it also makes it easy for technology and use-case assumptions to flow easily from one application to the other, thereby coupling the two and making the system brittle.