Skip to content

Commit aa5babc

Browse files
sahsisunnysahsisunny
authored
DOC : Updates to Requests API Contracts (#178)
* Doc : added api contracts for /requests API. * fix: fix api user
1 parent fca856e commit aa5babc

File tree

1 file changed

+262
-0
lines changed

1 file changed

+262
-0
lines changed

‎requests/README.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Requests API Contract
2+
3+
The Requests API provides endpoints for creating, fetching, and updating requests. The API contract details the available routes, request and response structures, query parameters, headers, cookies, and error handling.
4+
5+
| Route | Description |
6+
| ------------------------------------ | ----------------------------------------------------------------- |
7+
| [GET /requests](#get-requests) | Returns a list of requests with pagination and filtering options. |
8+
| [POST /requests](#post-requests) | Creates a new request. |
9+
| [PUT /requests/:id](#put-requestsid) | Updates an existing request. |
10+
11+
### **GET /requests**
12+
13+
Returns a list of requests with pagination and filtering options.
14+
15+
- **Description:** Fetches a list of requests, optionally filtered by various parameters.
16+
17+
- **URL:** `https://api.realdevsquad.com/requests?dev=true`
18+
19+
- **Method:** GET
20+
21+
- **Query Parameters:**
22+
23+
- `dev`: Required boolean to fetch requests.
24+
- `page`: Optional integer to specify the page number. Default is 1.
25+
- `size`: Optional integer to specify the number of requests per page. Default is 5.
26+
- `requestedBy`: Optional string to filter requests by the requester's username.
27+
- `type`: Optional string to filter requests by type (e.g., OOO).
28+
- `state`: Optional string to filter requests by state (e.g., APPROVED, REJECTED).
29+
30+
- **Headers:**
31+
32+
- Content-Type: application/json
33+
34+
- **Cookie:**
35+
36+
- rds-session: `<JWT>`
37+
38+
- **Success Response:**
39+
40+
- **Code:** 200
41+
- **Content:**
42+
```json
43+
{
44+
"message": "Request fetched successfully",
45+
"data": [
46+
{
47+
"id": "string",
48+
"createdAt": "number",
49+
"requestedBy": "string",
50+
"from": "number",
51+
"until": "number",
52+
"type": "string",
53+
"message": "string",
54+
"reason": "string",
55+
"lastModifiedBy": "string",
56+
"state": "string",
57+
"updatedAt": "number"
58+
},
59+
{
60+
"id": "string",
61+
"createdAt": "number",
62+
"requestedBy": "string",
63+
"from": "number",
64+
"until": "number",
65+
"type": "string",
66+
"message": "string",
67+
"reason": "string",
68+
"lastModifiedBy": "string",
69+
"state": "string",
70+
"updatedAt": "number"
71+
}
72+
// Additional request objects
73+
],
74+
"next": "string",
75+
"prev": "string"
76+
}
77+
```
78+
79+
- **Error Responses:**
80+
81+
- **Code:** 500
82+
- **Content:** `{ "statusCode": 500, "error": "Internal Server Error", "message": "An internal server error occurred" }`
83+
84+
- **Not Found Response:**
85+
86+
- **Code:** 204
87+
- **Content:** No content
88+
89+
- **Notes:**
90+
- Pagination is applied using the `page` and `size` parameters.
91+
- Filtering options are available using parameters like `requestedBy`,`type`, and `state`.
92+
- The response includes a list of request objects with their respective properties.
93+
94+
### Authentication and Authorization:
95+
96+
- Authentication is required for accessing this endpoint.
97+
98+
### Additional Notes:
99+
100+
- The provided response includes details of each request, such as ID, timestamps, requester, type, message, state, etc.
101+
- Pagination functionality is implemented using `next` and `prev` parameters in the response.
102+
- Error handling is provided for internal server errors (status code 500).
103+
104+
This API contract details the GET method for fetching requests, including all available query parameters, response structure, potential error responses, authentication, authorization requirements, and additional notes.
105+
106+
### **POST /requests**
107+
108+
Creates a new request.
109+
110+
- **Description:** Creates a new request with the provided details.
111+
112+
- **URL:** `https://api.realdevsquad.com/requests?dev=true`
113+
114+
- **Query Parameters:**
115+
116+
- `dev`: Required boolean to create requests in developer mode.
117+
118+
- **Method:** POST
119+
120+
- **Headers:**
121+
122+
- Content-Type: application/json
123+
124+
- **Cookie:**
125+
126+
- rds-session: `<JWT>`
127+
128+
- **Request Body:**
129+
130+
- Body Parameters:
131+
132+
- `type`: Required string to specify the type of request (e.g., OOO).
133+
- `from`: Required number to specify the start timestamp of the request.
134+
- `until`: Required number to specify the end timestamp of the request.
135+
- `message`: Required string to specify the message for the request.
136+
- `state`: Required string to specify the state of the request (e.g., PENDING).
137+
138+
- Example:
139+
```json
140+
{
141+
"type": "OOO",
142+
"from": "<timestamp>",
143+
"until": "<timestamp>",
144+
"message": "string",
145+
"state": "PENDING"
146+
}
147+
```
148+
149+
- **Success Response:**
150+
151+
- **Code:** 200
152+
- **Content:**
153+
```json
154+
{
155+
"message": "Request created successfully",
156+
"data": {
157+
"id": "string",
158+
"createdAt": "number",
159+
"updatedAt": "number",
160+
"requestedBy": "string",
161+
"type": "string",
162+
"from": "number",
163+
"until": "number",
164+
"message": "string",
165+
"state": "string"
166+
}
167+
}
168+
```
169+
170+
- **Error Responses:**
171+
- **Code:** 400
172+
- **Content:** `{ "statusCode": 400, "error": "Bad Request", "message": "Request already exists. Please wait for approval or rejection" }`
173+
- **Code:** 500
174+
- **Content:** `{ "statusCode": 500, "error": "Internal Server Error", "message": "An internal server error occurred" }`
175+
176+
### Authentication and Authorization:
177+
178+
- Authentication is required for creating a new request.
179+
180+
### Additional Notes:
181+
182+
- The request body should contain the necessary details for creating a new request, including type, timestamps for from and until, message, and state.
183+
- The state is set to "PENDING" by default.
184+
- Error handling is provided for cases where the request already exists and for internal server errors.
185+
186+
### **PUT /requests/:id**
187+
188+
Updates an existing request with the provided details.
189+
190+
- **Description:** Updates an existing request with the provided details.
191+
192+
- **URL:** `https://api.realdevsquad.com/requests/:id`
193+
194+
- **Method:** PUT
195+
196+
- **Path Parameters:**
197+
198+
- `id`: The unique identifier of the request to be updated.
199+
200+
- **Query Parameters:**
201+
202+
- `dev`: Required boolean to update requests in developer mode.
203+
204+
- **Headers:**
205+
- Content-Type: application/json
206+
- **Cookie:**
207+
208+
- rds-session: `<JWT>`
209+
210+
- **Request Body:**
211+
212+
- Body Parameters:
213+
214+
- `type`: Required string to specify the type of request (e.g., OOO).
215+
- `reason`: Optional string to specify the reason for the request.
216+
- `state`: Required string to specify the state of the request (e.g., APPROVED or REJECTED).
217+
218+
- Example:
219+
```json
220+
{
221+
"type": "OOO",
222+
"reason": "string",
223+
"state": "APPROVED"
224+
}
225+
```
226+
227+
- **Success Response:**
228+
229+
- **Code:** 200
230+
- **Content:**
231+
```json
232+
{
233+
"message": "Request approved successfully",
234+
"data": {
235+
"id": "string",
236+
"updatedAt": "number",
237+
"lastModifiedBy": "string",
238+
"type": "string",
239+
"reason": "string",
240+
"state": "APPROVED"
241+
}
242+
}
243+
```
244+
245+
- **Error Responses:**
246+
- **Code:** 400
247+
- **Content:** `{ "statusCode": 400, "error": "Bad Request", "message": "Request already approved" }`
248+
- **Code:** 500
249+
- **Content:** `{ "statusCode": 500, "error": "Internal Server Error", "message": "An internal server error occurred" }`
250+
251+
### Authentication and Authorization:
252+
253+
- Authentication is required for accessing this endpoint.
254+
255+
### Additional Notes:
256+
257+
- The request body should contain the necessary details for updating an existing request, including type, reason, and state.
258+
- Error handling is provided for cases where the request is already approved and for internal server errors.
259+
260+
## Conclusion
261+
262+
The Requests API contract provides detailed information about the available routes, request and response structures, query parameters, headers, cookies, error handling, and authentication and authorization requirements. It also includes additional notes for each endpoint to provide further context and guidance. This contract serves as a comprehensive reference for developers who need to interact with the Requests API.

0 commit comments

Comments
 (0)