From 616d83fd4738f9de6e4da97ca8f4e8dc74f77057 Mon Sep 17 00:00:00 2001 From: preciousBlessed Date: Fri, 22 Sep 2023 20:51:42 +0100 Subject: [PATCH] Added Request and Response Formats --- README.md | 210 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 190 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index ce5027eb..d958d502 100644 --- 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,22 +75,24 @@ 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 @@ -86,7 +100,7 @@ This API is equipped with functionalities to dynamically handle request/response |:---|:---------------:|:------------| |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": "markessien1000@hng.org" + "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": "markessien1000@hng.org" + "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": "mynewemail@hng.org", + "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) \ No newline at end of file