When designing an api you should think about
- Proper http verbs and response codes for different CRUD operations
- Think about versioning.
General guidelines to keep in mind:
-> Always prefer to use lowercase characters in uri’s. A forward slash should be used to indicate a hierarchical relationship. Also a trailing forward slash should be not be included. Hyphens (-) can be used for better readability but underscores ( _ ) should not be used.
Note: File extensions like ‘json’ or ‘xml’ should not be used to indicate a format preference. You should look at the ‘Content-Type’ header to determine how to process the body’s content.
-> The uri path should convey the resource model with each segment path identifying an addressable resource.
-> The actual words in the path should either be a singular ,plural noun or a verb.
Note: Do not use CRUD function names in the uri’s. You can use the query component of the uri for pagination.
-> GET and POST must not be used to tunnel other request methods
-> POST must be used to execute controllers
-> HEAD should be used to retrieve response headers
|200 (OK)||Non-specific Success.Must not be used to communicate errors in response body.|
|201 (OK)||Successful resource creation.|
|204 (No content)||Used when response body is intentionally empty|
|301(“Moved Permanently”)||Should be used to relocate resources|
|302 (“Found”)||Should not be used|
|303 (“See Other”)||Should be used to refer the client to a different URI|
|307 (“Temporary Redirect”)||Should be used to tell clients to resubmit the request to another URI|
|400 (“Bad Request”)||Used to indicate nonspecific failure|
|401 (“Unauthorized”)||Used when there is a problem with the client’s credentials|
|403 (“Forbidden”)||Used to forbid access regardless of authorization state|
|404 (“Not Found”)||Used when a client’s URI cannot be mapped to a resource|
|405 (“Method Not Allowed”)||Used when the HTTP method is not supported|
|406 (“Not Acceptable”)||Used when the requested media type cannot be served|
|415 (“Unsupported Media Type”)||Used when the media type of a request’s payload cannot be processed|
|500 (“Internal Server Error”)||Used to indicate API malfunction|
-> Content-Type, Content-Length should be used
Note: Cache-Control, Expires, and Date response headers should be used to encourage caching.Expiration caching headers should be used with 200 (“OK”) responses
-> Custom HTTP headers must not be used to change the behavior of HTTP methods
A consistent form should be used to represent errors and error responses.Consistent error types should be used for common error conditions.