Added Request and Response Formats

hngx-org · Sep 22, 2023 · 616d83f · 616d83f
1 parent 8947626
commit 616d83f
Showing 1 changed file with 190 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -13,8 +13,14 @@ Click and navigate to any section of your choice.
     - [Models, ERD and Database SetUp](#models-erd-and-database-setup)
     - [Simple Setup Instructions](#simple-setup-instructions)
     - [Sample API Usage](#sample-api-usage)
+  - [Request and Response Formats for Endpoint Testing](#request-and-response-formats-for-endpoint-testing)
+    - [Registering a New User Account](#registering-a-new-user-account)
+    - [Logging in A User](#logging-in-a-user)
+    - [Updating A User](#updating-a-user)
+    - [Sending Lunch](#sending-lunch)
+    - [Redeeming Lunch](#redeeming-lunch)
   - [Environmental Variables](#environmental-variables)
-  - [Major Packages and Dependencies](#major-packages-and-dependencies)
+    - [Major Packages and Dependencies](#major-packages-and-dependencies)
   - [Contributors](#contributors)
 
 ## Getting Started
@@ -46,8 +52,14 @@ This API is equipped with functionalities to dynamically handle request/response
     - [Models, ERD and Database SetUp](#models-erd-and-database-setup)
     - [Simple Setup Instructions](#simple-setup-instructions)
     - [Sample API Usage](#sample-api-usage)
+  - [Request and Response Formats for Endpoint Testing](#request-and-response-formats-for-endpoint-testing)
+    - [Registering a New User Account](#registering-a-new-user-account)
+    - [Logging in A User](#logging-in-a-user)
+    - [Updating A User](#updating-a-user)
+    - [Sending Lunch](#sending-lunch)
+    - [Redeeming Lunch](#redeeming-lunch)
   - [Environmental Variables](#environmental-variables)
-  - [Major Packages and Dependencies](#major-packages-and-dependencies)
+    - [Major Packages and Dependencies](#major-packages-and-dependencies)
   - [Contributors](#contributors)
 
 ### Endpoint Consumption Summary Table
@@ -63,30 +75,32 @@ This API is equipped with functionalities to dynamically handle request/response
 |5.| Get Me | `/api/users/me` | `GET` |Fetches a user profile| _Admin/User_ |
 |6.| Get User by id | `/api/users/:id` | `GET` |Finds a user by id| _Admin/User_ |
 |7.| Get All Users | `/api/users/` | `GET` |Finds all users for an organization| _Admin_ |
-|8.| Update User | `/api/user/:id` | `PUT` |Updates a user by id| _Admin/User_ |
-|9.| Delete User| `/api/users/:id` | `DELETE` |Deletes a user| _Admin/User_ |
-|10.| Logout User | `/api/auth/logout` | `POST` |For loggin a user out| _Admin/User_ |
+|8.| Forget Password | `/api/users/forget-password` | `POST` |Initiates reseting procedures| _Admin/User_ |
+|9.| Reset Password | `/api/users/reset-password` | `PATCH` |Resets User Password| _Admin/User_ |
+|10.| Update User | `/api/user/:id` | `PUT` |Updates a user by id| _Admin/User_ |
+|11.| Delete User| `/api/users/:id` | `DELETE` |Deletes a user| _Admin/User_ |
+|12.| Logout User | `/api/auth/logout` | `POST` |For loggin a user out| _Admin/User_ |
 |   |                  |_**Organization Routes**_ (`/api/organization`)||
-|11.| Create Organization| `/api/organization/create`| `POST`| Creates new organization | _Admin_ |
-|12.| Confirm Invite | `/api/organization/confirm-invite` | `POST`| Confirms invite to an org. | _Admin_ |
-|13.| Send Invite | `/api/organization/send-invite` | `POST`| Sends user an invite to join org. | _Admin_ |
-|14.| Update Organization | `/api/organization/update-info` | `PUT`| Updates the organization details | _Admin_ |
+|13.| Create Organization| `/api/organization/create`| `POST`| Creates new organization | _Admin_ |
+|14.| Confirm Invite | `/api/organization/confirm-invite` | `POST`| Confirms invite to an org. | _Admin_ |
+|15.| Send Invite | `/api/organization/send-invite` | `POST`| Sends user an invite to join org. | _Admin_ |
+|16.| Update Organization | `/api/organization/update-info` | `PUT`| Updates the organization details | _Admin_ |
 |   |                  |_**Lunch Routes**_ (`/api/lunch`)||
-|15.| Get All Lunch | `/api/lunch/` | `GET`| Fetches all available lunch | _Admin/User_ |
-|16.| Gift Lunch | `/api/lunch/send/:id` | `POST`| Send lunch to a user by id | _Admin/User_ |
-|17.| Get Lunch Detail | `/api/lunch/:lunchId` | `GET`| Fetches details for a lunch by id | _Admin/User_ |
-|18.| Get Lunch by UserID | `/api/lunch/user/:userId` | `GET`| Fetches lunch for a user by id | _Admin/User_ |
+|17.| Get All Lunch | `/api/lunch/` | `GET`| Fetches all available lunch | _Admin/User_ |
+|18.| Gift Lunch | `/api/lunch/send` | `POST`| Send lunch to a user | _Admin/User_ |
+|19.| Get Lunch Detail | `/api/lunch/:lunchId` | `GET`| Fetches details for a lunch by id | _Admin/User_ |
+|20.| Get Lunch by UserID | `/api/lunch/user/:userId` | `GET`| Fetches lunch for a user by id | _Admin/User_ |
 |   |                  |_**Withdrawal[Redeem] Routes**_ (`/api/withdrawals`)||
-|19.| Redeem Lunch | `/api/withdrawals/withdraw` | `POST`| withdraws the monetary value for a lunch | _Admin/User_ |
-|20.| Withdrawal History | `/api/withdrawals/history` | `GET`| withdraws the monetary value for a lunch | _Admin/User_ |
+|21.| Redeem Lunch | `/api/withdrawals/withdraw` | `POST`| withdraws the monetary value for a lunch | _Admin/User_ |
+|22.| Withdrawal History | `/api/withdrawals/history` | `GET`| withdraws the monetary value for a lunch | _Admin/User_ |
 
 ### Request Methods Response Formats and Status Codes Used
 
 |S/N | Request Methods | Description |
 |:---|:---------------:|:------------|
 |1. | `GET` | Fetch item(s) |
 |2. | `POST` | Send item(s) |
-|3. | `PUT` or `PATCH` | Update item(s) |
+|3. | `PUT` | Update item(s) |
 |4. | `DELETE` | Remove or Delete item(s) |
 
 |S/N | Status Code | Description |
@@ -119,8 +133,164 @@ nodemon app.js
 ```
 The application starts running and listening on the port defined in `process.env.PORT`. A message will be printed on the console to show that your app is running and has connected to the database. You can access the `MYSQL` database from the `CLI`, on a hosted cloud platform or any `MYSQL` server such as the one provided by `MYSQL` workbench.
 
-### Sample API Usage 
-Visit this [link](url) to view more about the `API` on `Swagger.io`
+### Sample API Usage
+The Requests and Responses in the [next section](#request-and-response-formats-for-endpoint-testing) demonstrates the testing and use of some core functionalities in the `Free Lunch App API`.
+
+## Request and Response Formats for Endpoint Testing
+We will demonstrate the performance of requests and `reception` of `responses` on some select `endpoints`: `Register a User`, `Login`, `Update a User`, `Send Lunch` and `Redeem Lunch`, as these describes the core functionality of the `Free Lunch Application`.
+
+Navigate to any section of your choice or kindly stick to the flow!
+
+- [Registering a New User Account](#registering-a-new-user-account)
+- [Logging in A User](#logging-in-a-user)
+- [Updating A User](#updating-a-user)
+- [Sending Lunch](#sending-lunch)
+- [Redeeming Lunch](#redeeming-lunch)
+
+### Registering a New User Account
+- **Endpoint**: `/api/auth/signup`
+- **Method**: `POST`
+- **Description**: The steps for initializing a new user who has been granted access via invite.
+- **Request Body**:
+```
+{
+    "first_name" : "Mark"
+    "last_name" : "Essien"
+    "email": "[email protected]"
+    "phone" : "1234567890"
+    "org_id" : "some_id"
+    "password" : "a-good-password"
+    "lunch_credit_balance" : 1000
+    "is_admin" : false
+    "bank_code" : "B-CODE"
+    "bank_name" : "B-NAME"
+    bank_number : "ACCOUNT-NUMBER"
+}
+```
+
+- **Response Body `JSON`**:
+- **Status Code**: `201`
+```
+{
+    "success": true,
+    "message": "User registered successfully",
+    "data": {
+            "user": newUser,
+    },
+}
+```
+
+### Logging in A User
+- **Endpoint**: `/api/auth/login`
+- **Method**: `POST`
+- **Description**: The steps for logging in a user who has created an account under an organization.
+- **Request Body**:
+```
+{
+    "email": "[email protected]"
+    "password" : "a-good-password"
+}
+```
+
+- **Response Body `JSON`**:
+- - **Status Code**: `200`
+```
+{
+    "success": true,
+    "message": "User authenticated successfully",
+    "data": {
+            "user": user,
+    },
+}
+```
+### Updating A User
+- **Endpoint**: `/api/user/:userId`
+- **Method**: `PUT`
+- **Description**: The steps for upating a user who already has an account with the organization. Any field not provided in the body as shown will remain unchanged from it's previous value.
+- **Request Body**:
+```
+{
+    "first_name" : "MyNewFirstName",
+    "last_name" : "MyNewSurname",
+    "email": "[email protected]",
+    "profile_pic" : "LINK-to-PIC",
+    "bank_name" : "NewBankName",
+    "bank_code" : "NEW-BANK-CODE",
+    "bank_number" : "NEW-ACCOUNT-NUMBER",
+}
+```
+
+- **Response Body `JSON`**:
+- - **Status Code**: `200`
+```
+{
+    "success" : true,
+    "message" : "User updated successfully",
+    "data" : {
+        "user" : user,
+    },
+}
+```
+
+### Sending Lunch
+- **Endpoint**: `/api/lunch/send`
+- **Method**: `POST`
+- **Description**: The steps for sending lunch to a user who's id is known.
+- **Request Body**:
+```
+{
+    "receiverId" : "THE-RECEIVER-ID",
+    "quantity" : 2,
+    "note: "With hearetfelt care, I send you this gift. You've been a wonderful staff!",
+}
+```
+
+- **Response Body `JSON`**:
+- **Status Code**: `200`
+```
+{
+    "success" : true,
+    "message" : "Lunch sent successfully",
+    "data" : {
+      "sender_id" : "ID-OF-SENDER",
+      "receiver_id": "THE-RECEIVER-ID",
+      quantity : 2,
+      "note" : "With hearetfelt care, I send you this gift. You've been a wonderful staff!"
+    }
+}
+```
+
+### Redeeming Lunch
+- **Endpoint**: `/api/withdrawals/withdraw`
+- **Method**: `POST`
+- **Description**: The steps for redeeming/withdrawing lunch-monetary value to a user's bank account.
+- **Request Body**:
+```
+{
+    "bank_number" : "ACCOUNT-NUMBER",
+    "bank_name" : "BANK-NAME",
+    "bank_code" : "BANK-CODE",
+    "amount" : 2
+}
+```
+
+- **Response Body `JSON`**:
+- **Status Code**: `200`
+```
+{
+    "message" : "Withdrawal request created successfully",
+    "statusCode" : 201,
+      "data" : {
+        "id" : "ID-OF-DB-FIELD", 
+        "user_id": "USER-ID",
+        "status" : "success",
+        "amount" : 2,
+        "created_at" : "TIME OF COMPLETION OF WITHDRAWAL",
+      }
+}
+```
+
+Visit this [link](url) to view more about the `API` (request, response and endpoints) on `Swagger.io`
 
 ## Environmental Variables
 For effectively testing the API, these credentials were setup in the `.env` file in the root of the repo:
@@ -134,7 +304,7 @@ For effectively testing the API, these credentials were setup in the `.env` file
 `JWT_SIGNATURE= *QSJfus1TOH2fSHw41Ifo0LMN2fzeQD*`
 ```
 
-## Major Packages and Dependencies
+### Major Packages and Dependencies
 - `dotenv`
 - `express`
 - `nodemon`
@@ -153,4 +323,4 @@ See more `dev-dependencies` in the [`package.json`](package.json) file.
 
 ## Contributors
 @ Team Lightning, September 2023
-[Move back up](#free-lunch-app)
+[Move back up](#free-lunch-app)