added status code and example in get/post/put/delete methods

Author: anishmanandhar

docs/rest-api/delete.md

@@ -4,4 +4,21 @@ title: Delete Method
 sidebar_label: Delete
 ---
 
-#### The following convention should be followed for Delete
+As the name applies, **DELETE** APIs are used to delete resources (identified by the Request-URI).
+
+A successful response of DELETE requests SHOULD be HTTP response code 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has been queued, or 204 (No Content) if the action has been performed but the response does not include an entity.
+
+DELETE operations are idempotent. If you DELETE a resource, it’s removed from the collection of resources. Repeatedly calling DELETE API on that resource will not change the outcome – however, calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed. Some may argue that it makes the DELETE method non-idempotent. It’s a matter of discussion and personal opinion.
+
+If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
+
+> * **/employees/{employee-id}**
+> * **/departments/{department-id}**
+
+|  Response code            |  Result/Reason |
+|---------------------------|------------------------------|
+|200 OK                     | Sucessfully deleted the Enity.|
+|401 (Unauthorized)         | Invalid Credentials/ Invalid Authentication |
+|403 (Forbidden)            | Invalid Authorization/ Insufficient rights/ Incorrect Role |  
+|405 (Method Not allowed)   | If API supports methods other than PUT request |
+|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

docs/rest-api/get.md

@@ -10,6 +10,10 @@ Use **GET requests** to retrieve resource representation/information only – an
 > * **/employees/{employee-id}/leaves**
 > * **/employees/{employee-id}/employee-reports**
 
+Use query params to filter response or get subset or limited resource.
+
+> * **/employees/{employee-id}/leaves?type={leave-type}&order-by={leave-date}**
+
 |  Response code            |  Result/Reason |
 |---------------------------|------------------------------|
 |200 OK                     | Sucessfully Fetched the Enity. <br/> Must include a response body. |

docs/rest-api/naming-convention.md

@@ -16,3 +16,36 @@ In REST(**REpresentational State Transfer**), primary data **representation** is
 
 > * **/customer/{customer-id}/check-validity**
 > * **/customer/{customer-id}/cart/checkout**
+
+* Use forward slash (/) to indicate hierarchical relationships
+  
+> **/customers/{customer-id}/accounts/{account-id}/balance**
+> **/category/{cateogry-id}/products/{product-id}/balance**
+
+* Do not use trailing forward slash (/) in URIs
+
+> * **/employees** //Good practice
+> * **/employees/{employee-id}/leaves/** //Bad practice
+
+* Use hyphens (-) to improve the readability of URIs
+  
+> * **/employees/{employee-id}/employee-reports** //Readable
+> * **/customer/{customer-id}/check-validity** //Readable
+>
+> * **/employees/{employee-id}/employeeReports** //Less Readable
+> * **/customer/{customer-id}/checkValidity** //Less Readable
+
+* Do not use file extentions and underscores
+
+> * **/employees/{employee-id}/employee-reports.pdf** /*Bad Practice*/
+> * **/employees/{employee-id}/employee_reports** /*Bad Practice*/
+
+* Never use CRUD function names in URIs
+  
+URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.
+
+> * GET Request  **/employees** // Get all employees
+> * POST Request  **/employees** // Create new employees
+> * GET Request  **/employees/{employee-id}** // Get one employee with given id
+> * PUT Request  **/employees/{employee-id}** // Update one employee with given id
+> * DELETE Request  **/employees/{employee-id}** // Delete one employee with given id

docs/rest-api/post.md

@@ -7,17 +7,15 @@ sidebar_label: Post
 Use **POST requests** to create new subordinate resources, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table. Talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.Note that POST is **neither safe nor idempotent**, and invoking two identical POST requests will result in two different resources containing the same information (except resource ids).
 
 > * **/employees**
-> * **/employees/{employee-id}/leaves**
-> * **/employees/{employee-id}/employee-reports**
+> * **/departments**
 
 |  Response code            |  Result/Reason |
 |---------------------------|------------------------------|
-|201 OK                     | Sucessfully Created the Enity. <br/> Must include a response body. |
+|201 (Created)              | Sucessfully Created the Enity. <br/> Must include a response body. |
 |202 (Accepted)             | Actions that take a long while to process/ Batch/Queue Oriented Process |
 |204 (No Content)           | When the REST API declines to send back any status message or representation in the response message’s body. Must not contains the response body|
 |401 (Unauthorized)         | Invalid Credentials/ Invalid Authentication |
 |403 (Forbidden)            | Invalid Authorization/ Insufficient rights/ Incorrect Role |
 |400 (Bad Request)           | Bad request object | validation error |
-|405 (Method Not allowed)   | If API supports methods other than GET request |
-|410 (Gone)                 | Expired link/Server no longer serve this request.|
+|405 (Method Not allowed)   | If API supports methods other than POST request |
 |500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

docs/rest-api/put.md

@@ -4,4 +4,18 @@ title: Put Method
 sidebar_label: Put
 ---
 
-#### The following convention should be followed for Put
+Use **PUT** APIs primarily to update existing resource (if the resource does not exist, then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
+
+> * **/employees/{employee-id}**
+> * **/departments/{department-id}**
+
+|  Response code            |  Result/Reason |
+|---------------------------|------------------------------|
+|200 OK                     | Sucessfully updated the Enity. <br/> Must include a response body. |
+|204 (No Content)           | When the REST API declines to send back any status message or representation in the response message’s body. Must not contains the response body|
+|401 (Unauthorized)         | Invalid Credentials/ Invalid Authentication |
+|403 (Forbidden)            | Invalid Authorization/ Insufficient rights/ Incorrect Role |
+|400 (Bad Request)          | Bad request object | validation error |
+|404 (Not found)            |  If ID not found or invalid|
+|405 (Method Not allowed)   | If API supports methods other than PUT request |
+|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|