Skip to content

Commit a9b5800

Browse files
anishmanandharanishmanandhar
committed
add request body and response body for different request method type
1 parent 0d8f233 commit a9b5800

File tree

6 files changed

+338
-13
lines changed

6 files changed

+338
-13
lines changed

‎docs/rest-api/get.md

Lines changed: 69 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,82 @@ title: Get Method
44
sidebar_label: Get
55
---
66

7+
8+
### Introduction
9+
710
Use **GET requests** to retrieve resource representation/information only – and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. Additionally, GET APIs should be **idempotent**, which means that making multiple identical requests must produce the same result every time until another API (POST/PUT/PATCH/DELETE) has changed the state of the resource on the server.
811

12+
* **Avoid using request body in GET request**
13+
14+
* Use `path params` instead of `query params` if its a must value to process a request. This way we can reduce unnucessary validation checks.
15+
16+
* Use `query params` to filter response or get subset or limited resource.
17+
18+
### URL Example
19+
920
> * **/employees**
1021
> * **/employees/{employee-id}/leaves**
1122
> * **/employees/{employee-id}/employee-reports**
23+
> * **/employees/{employee-id}/leaves?type={leave-type}&order-by={leave-date}**
1224
13-
Use query params to filter response or get subset or limited resource.
25+
### Success Response Body
1426

15-
> * **/employees/{employee-id}/leaves?type={leave-type}&order-by={leave-date}**
27+
* Expecting a single resource [**/employees/1**]
28+
29+
```yaml
30+
{
31+
"id": 1,
32+
"name": "John Doe",
33+
"email": "[email protected]",
34+
"address": "123 Mockingbird Lane",
35+
"city": "New York",
36+
"state": "NY",
37+
"zip": "10001"
38+
}
39+
```
40+
41+
* Expecting collection resource [**/employees**]
42+
43+
```yaml
44+
[
45+
{
46+
"id": 1,
47+
"name": "John Doe",
48+
"email": "[email protected]",
49+
"address": "123 Mockingbird Lane",
50+
"city": "New York",
51+
"state": "NY",
52+
"zip": "10001"
53+
},
54+
{
55+
"id": 2,
56+
"name": "William",
57+
"email": "[email protected]",
58+
"address": "123 Mockingbird Lane",
59+
"city": "New York",
60+
"state": "NY",
61+
"zip": "10001"
62+
}
63+
]
64+
```
65+
66+
### Error Response Body
67+
68+
```yaml
69+
{
70+
"error": "Invalid payoad.",
71+
"detail": {
72+
"name": "This field is required."
73+
}
74+
}
75+
76+
```
77+
78+
### Response Header
79+
80+
Specify `Content-type` header, and its should be `application/json` while returing json response, `application/xml` while returning xml response and so on.
81+
82+
### Response code and Results
1683

1784
| Response code | Result/Reason |
1885
|---------------------------|------------------------------|

‎docs/rest-api/hateaos.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/rest-api/patch.md

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,85 @@ title: Patch Method
44
sidebar_label: Patch
55
---
66

7-
#### The following convention should be followed for Patch
7+
PATCH is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
8+
9+
This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version.PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame. Collisions from multiple PATCH requests may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point or else they will corrupt the resource. Clients using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource.
10+
11+
*PATCH request can usuallly be used to update the status of resource like from `pending` to `accepted`, `active` to `expired`*
12+
13+
> * **/employees/{employee-id}**
14+
> * **/departments/{department-id}**
15+
16+
### Request Body
17+
18+
* Patch updating a single resource [**/employees/1**]
19+
20+
```yaml
21+
{
22+
"email": "[email protected]"
23+
}
24+
```
25+
26+
* Creating collection resource [**/employees**]
27+
28+
```yaml
29+
[
30+
{
31+
"id":"1",
32+
"email": "[email protected]"
33+
},
34+
{
35+
"id":"2",
36+
"address": "123 Mockingbird Lane"
37+
}
38+
]
39+
```
40+
41+
### Response Body
42+
43+
* Patch updating a single resource [**/employees**]
44+
45+
```yaml
46+
{
47+
"id":"1",
48+
"email": "[email protected]"
49+
}
50+
```
51+
52+
* Patch updating collection resource [**/employees**]
53+
54+
```yaml
55+
[
56+
{
57+
"id":"1",
58+
"email": "[email protected]"
59+
},
60+
{
61+
"id":"2",
62+
"address": "123 Mockingbird Lane"
63+
}
64+
]
65+
```
66+
67+
### Error Response Body
68+
69+
```yaml
70+
{
71+
"error": "Invalid payoad.",
72+
"detail": {
73+
"name": "This field is required."
74+
}
75+
}
76+
77+
```
78+
79+
| Response code | Result/Reason |
80+
|---------------------------|------------------------------|
81+
|200 OK | Sucessfully updated the Enity. <br/> Must include a response body. |
82+
|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|
83+
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
84+
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |
85+
|400 (Bad Request) | Bad request object | validation error |
86+
|404 (Not found) | If ID not found or invalid|
87+
|405 (Method Not allowed) | If API supports methods other than PUT request |
88+
|500 (Internal server error)| Server encountered an unexpected condition that prevented it from fulfilling the request.|

‎docs/rest-api/post.md

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,101 @@ Use **POST requests** to create new subordinate resources, e.g., a file is subor
99
> * **/employees**
1010
> * **/departments**
1111
12+
### Request Body
13+
14+
* Creating a single resource [**/employees**]
15+
16+
```yaml
17+
{
18+
"name": "John Doe",
19+
"email": "[email protected]",
20+
"address": "123 Mockingbird Lane",
21+
"city": "New York",
22+
"state": "NY",
23+
"zip": "10001"
24+
}
25+
```
26+
27+
* Creating collection resource [**/employees**]
28+
29+
```yaml
30+
[
31+
{
32+
"name": "John Doe",
33+
"email": "[email protected]",
34+
"address": "123 Mockingbird Lane",
35+
"city": "New York",
36+
"state": "NY",
37+
"zip": "10001"
38+
},
39+
{
40+
"name": "William",
41+
"email": "[email protected]",
42+
"address": "123 Mockingbird Lane",
43+
"city": "New York",
44+
"state": "NY",
45+
"zip": "10001"
46+
}
47+
]
48+
```
49+
50+
### Response Body
51+
52+
* Creating a single resource [**/employees**]
53+
54+
```yaml
55+
{
56+
"id":"1",
57+
"name": "John Doe",
58+
"email": "[email protected]",
59+
"address": "123 Mockingbird Lane",
60+
"city": "New York",
61+
"state": "NY",
62+
"zip": "10001"
63+
}
64+
```
65+
66+
* Creating collection resource [**/employees**]
67+
68+
```yaml
69+
[
70+
{
71+
"id":"1",
72+
"name": "John Doe",
73+
"email": "[email protected]",
74+
"address": "123 Mockingbird Lane",
75+
"city": "New York",
76+
"state": "NY",
77+
"zip": "10001"
78+
},
79+
{
80+
"id":"2",
81+
"name": "William",
82+
"email": "[email protected]",
83+
"address": "123 Mockingbird Lane",
84+
"city": "New York",
85+
"state": "NY",
86+
"zip": "10001"
87+
}
88+
]
89+
```
90+
91+
### Error Response Body
92+
93+
```yaml
94+
{
95+
"error": "Invalid payoad.",
96+
"detail": {
97+
"name": "This field is required."
98+
}
99+
}
100+
101+
```
102+
12103
| Response code | Result/Reason |
13104
|---------------------------|------------------------------|
14105
|201 (Created) | Sucessfully Created the Enity. <br/> Must include a response body. |
15-
|202 (Accepted) | Actions that take a long while to process/ Batch/Queue Oriented Process |
106+
|202 (Accepted) | Actions that take a long while to process/ Batch/Queue Oriented Process Or resource will be created as a result of future processing |
16107
|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|
17108
|401 (Unauthorized) | Invalid Credentials/ Invalid Authentication |
18109
|403 (Forbidden) | Invalid Authorization/ Insufficient rights/ Incorrect Role |

‎docs/rest-api/put.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,100 @@ Use **PUT** APIs primarily to update existing resource (if the resource does not
99
> * **/employees/{employee-id}**
1010
> * **/departments/{department-id}**
1111
12+
### Request Body
13+
14+
* Updating a single resource [**/employees/1**]
15+
16+
```yaml
17+
{
18+
"id":"1",
19+
"name": "John Doe",
20+
"email": "[email protected]",
21+
"address": "123 Mockingbird Lane",
22+
"city": "New York",
23+
"state": "NY",
24+
"zip": "10001"
25+
}
26+
```
27+
28+
* Creating collection resource [**/employees**]
29+
30+
```yaml
31+
[
32+
{
33+
"id":"1",
34+
"name": "John Doe",
35+
"email": "[email protected]",
36+
"address": "123 Mockingbird Lane",
37+
"city": "New York",
38+
"state": "NY",
39+
"zip": "10001"
40+
},
41+
{
42+
"id":"2",
43+
"name": "William",
44+
"email": "[email protected]",
45+
"address": "123 Mockingbird Lane",
46+
"city": "New York",
47+
"state": "NY",
48+
"zip": "10001"
49+
}
50+
]
51+
```
52+
53+
### Response Body
54+
55+
* Updating a single resource [**/employees**]
56+
57+
```yaml
58+
{
59+
"id":"1",
60+
"name": "John Doe",
61+
"email": "[email protected]",
62+
"address": "123 Mockingbird Lane",
63+
"city": "New York",
64+
"state": "NY",
65+
"zip": "10001"
66+
}
67+
```
68+
69+
* Updating collection resource [**/employees**]
70+
71+
```yaml
72+
[
73+
{
74+
"id":"1",
75+
"name": "John Doe",
76+
"email": "[email protected]",
77+
"address": "123 Mockingbird Lane",
78+
"city": "New York",
79+
"state": "NY",
80+
"zip": "10001"
81+
},
82+
{
83+
"id":"2",
84+
"name": "William",
85+
"email": "[email protected]",
86+
"address": "123 Mockingbird Lane",
87+
"city": "New York",
88+
"state": "NY",
89+
"zip": "10001"
90+
}
91+
]
92+
```
93+
94+
### Error Response Body
95+
96+
```yaml
97+
{
98+
"error": "Invalid payoad.",
99+
"detail": {
100+
"name": "This field is required."
101+
}
102+
}
103+
104+
```
105+
12106
| Response code | Result/Reason |
13107
|---------------------------|------------------------------|
14108
|200 OK | Sucessfully updated the Enity. <br/> Must include a response body. |

‎sidebars.js

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,7 @@ module.exports =
2121
]
2222
},
2323
"rest-api/security",
24-
"rest-api/versioning",
25-
"rest-api/hateaos"
24+
"rest-api/versioning"
2625
],
2726
"Github": [
2827
"git/branch-naming-convention",

0 commit comments

Comments
 (0)