Assignment - API DOC

# Assignment - API DOC This doc is a part of assignment for the Intership Opportunity from Truexam ## Stack and Technology - `server`, `Express JS` will be used with `NodeJS` as the environment - `database`, `MongoDB` as database and `Mongoose` for schema and performing operations in `NodeJS` - `libraries` - `express` for ExpressJS - `mongoose` for database related matter - `express-sessions` for session handling - `connect-mongo` for storing Express Sessions details - `bcrypt` for hashing the passwords - `multer` for handling files - `aws-sdk` for handling AWS S3 Bucket Uploads - `validator` for validations ## API lists ### - POST `/user/create` - To create new users Schema `application/json` ```javascript { name: __USER_NAME__, email: __USER_EMAIL__, contact: __PHONE_NUMBER__, track:__TRACK_TYPE__, password: __PASSWORD__, dor : __DATE_OF_REGISTRATION__ } ``` Special Points - Mandatory fields are `name`, `email`, `contact`, `track`, `password` - `dor` will be automatically created from server side - This is a public endpoint - `track` will be sanitised based on `Beginner`, `Intermidiate` and `Advanced` , Except that it will throw error - `email` must be valid (validation will be done through library `validator`) - `contact` must be a 10-digit valid number which can be made more validated by sending OTP or using a 3rd party library - Mandatory fields, if left empty or undefined will throw error Status Codes (Success and Error) `application/json` - `201` - User Created Successfully ```javascript { data : { _id : __MONGO_OBJECT_ID, //user_id name : __NAME__, email : __EMAIL__, track : __TRACK_TYPE__, password: __HASHED_SALTED_PASSWORD__, dor: __DATE_OF_REGISTRATION__ } } ``` - `406` - Not accepted due to improper data recieved - Data undefined ```javascript { error : '__FIELD__ undefined', errorOccured : '__FIELD__' } ``` - Data inccorect format (`track`, `email`, `contact`) ```javascript { erorr: '__FIELD__ incorrect format', errorOccured : '__FIELD__' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - POST `/instructor/create` - To create instructors account Schema `application/json` ```javascript { name: __INSTRUCTOR_NAME__, email: __INSTRUCTOR_EMAIL__, contact: __PHONE_NUMBER__, password: __PASSWORD__, doj : __DATE_OF_JOINING__ } ``` Special Points - Mandatory fields are `name`, `email`, `contact`, `password` - `doj` will be automatically created from server side - This is a public endpoint - `email` must be valid (validation will be done through library `validator`) - `contact` must be a 10-digit valid number which can be made more validated by sending OTP or using a 3rd party library - Mandatory fields, if left empty or undefined will throw error Status Codes (Success and Error) `application/json` - `201` - User Created Successfully ```javascript { data : { _id : __MONGO_OBJECT_ID, //instructor_id name : __NAME__, email : __EMAIL__, password: __HASHED_SALTED_PASSWORD__, doj: __DATE_OF_REGISTRATION__ } } ``` - - `406` - Not accepted due to improper data recieved - Data undefined (Mandatory fields not sent) ```javascript { error : '__FIELD__ undefined', errorOccured : '__FIELD__' } ``` - Data inccorect format (`email`, `contact`) ```javascript { erorr: '__FIELD__ incorrect format', errorOccured : '__FIELD__' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - GET `/:role/check/:email` - To check whether the email is already registered or not (instructor/user) Speacial Points - As per schema and design, one user can be registered with one email - `:role` is a param - whether the person is `user` or `instructor`. Accordingly that database will be searched - `:email` is a param where the email has to be passed for checking - This is an internal endpoint to be used in frontend for verifcation while email is entered Status Codes (Success and Error) `application/json` - `200` - OK - email not found - registration can be done ```javascript { canRegister : true } ``` - `404` - Email Found - Registration cannot be allowed in that email ```javascript { canRegister : false } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - POST `/task/new` - To create a new task Schema `application/json` ```javascript { name: __TASK_NAME__, desc: __DESCRIPTION_OF_THE_TASK__, imgUrl: __IMG_URL__, assignedTo : [ __USER_EMAIL_1__, __USER_EMAIL_2__, __USER_EMAIL_3__, ... ], deadline : __DATE__, assingedBy : __INSTRUCTOR_ID__ } ``` Special Points - All fields are mandatory - `desc` is a small description of the task that has to be created - `imgUrl` is a image url for the task provided by `POST /task/upload` - `assignedTo` is am array of users to whom the instructor assigned the task - `assignedBy` is the instructor's ID for future reference - `deadline` is the date for submission of the task - All data will be sanitized and validated - IMPORTANT : before using this endpoint please upload the images through the endpoint `POST /task/upload` which will return the image Urls to be used here Status Codes (Success and Error) `application/json` - `201` - User Created Successfully ```javascript { data : { _id : __TASK_ID, //instructor_id name : __NAME__, desc: __DESCRIPTION_OF_THE_TASK__, imgUrl: __IMG_URL__, assignedTo : [ __USER_EMAIL_1__, __USER_EMAIL_2__, __USER_EMAIL_3__, ... ], deadline : __DATE__, assingedBy : __INSTRUCTOR_ID__ } } ``` - - `406` - Not accepted due to improper data recieved - Data undefined (Mandatory fields not sent) ```javascript { error : '__FIELD__ undefined', errorOccured : '__FIELD__' } ``` - Data inccorect format ```javascript { erorr: '__FIELD__ incorrect format', errorOccured : '__FIELD__' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - POST `/task/upload` - To store the image in AWS S3 Storage Special Points `multipart/form-data` - To be stored in AWS S3 bucket - For this the image will be passed as `formdata` - The return will be an array of url/s if successfull in upload - the key must be named `image` as shown below JS Code ```javascript= var fd= new formData() fd.append('image', __THE_UPLOADED_IMAGE__) fetch(__URL__, { method: 'POST', body: fd, }) ``` Status Codes (Success and Error) `application/json` - `201` : All image upload successfull ```javascript { status: true, data:{ ... location : __IMG_URL__ //aws public link for the image ... } } ``` - `500` - Error in upload ```javascript { status: false, error:{ __AWS_DETAILED_ERROR_REPORT__ } } ``` ### - GET `/task/user/:userid` - To get the tasks assigned to the student Special Points - `:userid` is the student's userID Status Codes (Success and Error) `application/json` - `200` : Task details recieved ```javascript { data:[ { _id : __TASK_ID__, name : __TASK_NAME__, desc : __TASK_DESCRIPTION__, imgUrl : __IMG_URL__, deadline: __DEADLINE__, assignedBy : __INSTRUCTOR_NAME__, isEvaluated: __TRUE/FALSE__, grade : __GRADE_FROM_0_TO_5__, }, ... ] } ``` - `404` - Student/User not found ```javascript { error: `user not found`, errorOccured: 'user' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - POST `/task/submit` - To submit the task Schema `application/json` ```javascript { userId: __USER_ID__, taskId: __TASK_ID__, imgSubmitted : __IMG_URL__, } ``` Special Points - `imgSubmitted` is a image url for the task provided by `POST /task/upload` - IMPORTANT : before using this endpoint please upload the images through the endpoint `POST /task/upload` which will return the image url to be used here - `userid` and `taskid` should be valid Status Codes (Success and Error) `application/json` - `201` - Task submitted successfully ```javascript { submited : true, userId: __USER_ID__, taskId: __TASK_ID__, imgSubmitted : __IMG_URL__ } ``` - `404` - User/Task not found - User not found ```javascript { error : 'user not found', errorOccured : 'user' } ``` - Task not found ```javascript { error : 'task not found', errorOccured : 'task' } ``` - `500` - Error in upload ```javascript { status: false, error:{ __AWS_DETAILED_ERROR_REPORT__ } } ``` ### - GET `/task/instructor/:taskid` - To get the submitted task of all or particular student Special Points - `:taskid` is the taskId - This endpoint accepts queries - `?userid=__USER_ID__` - To get the submitted task of a particular user example : `/task/instructor/60d813cd4f976942bc67bd0c?userid=60d813cd4f976942bc67bd0d` - `if left empty or no query is passed` - To get the all the submitted tasks of those who have submitted example : `/task/instructor/60d813cd4f976942bc67bd0c` Status Codes (Success and Error) `application/json` - `200` : Data recieved - if query `?userid=` is passed ```javascript { data: { _id: __SUBMISSION_ID__, taskid : __TASKID__, userid : __USER_ID__, imgSubmitted : __IMG_URL__, isEvaluated : __TRUE/FALSE__, grade : __GRADE_FROM_0_TO_5__, } } ``` - if no query is passed ```javascript { data: [ { _id: __SUBMISSION_ID__, taskid : __TASKID__, userid : __USER_ID__, imgSubmitted : __IMG_URL__, isEvaluated : __TRUE/FALSE__, grade : __GRADE_FROM_0_TO_5__, }, ... ] } ``` - `404` - Not found - if `?userid=` query used ```javascript { error : `User/task not found` errorOccured : `user/task` } ```` - if `no query` is used ```javascript { error : 'task not found', errorOccured : 'task' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - POST `/task/evaluate` - To evaluate the task submitted Schema `application/json` ```javascript { submissionId : __SUBMISSION_ID__ grade : __FROM_1_to_5__, } ``` Special Points - `submissionId` must be valid - `grade` must be between 1 and 5. default is 0 if not corrected Status Codes (Success and Error) `application/json` - `201` - Evaluated successfully ```javascript { isEvaluated : true } ``` - `409` - Already evaluated ```javascript { data: { _id: __SUBMISSION_ID__, taskid : __TASKID__, userid : __USER_ID__, imgSubmitted : __IMG_URL__, isEvaluated : __TRUE/FALSE__, grade : __GRADE_FROM_0_TO_5__, } } ``` - `404` - submission not found ```javascript { error : 'submission not found', errorOccured: 'submission' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ### - GET `/task/result/:userid` - To get the results of the submitted and evaluated tasks Special Points - `userid` must be valid - This endpoint accepts queries - `?taskid=__TASK_ID__` : to get a particular details of a submitted task example : `/task/result/60d813cd4f976942bc67bd0e?taskid=60d813164f976942bc67bcfe` - no query - get all the details of submitted task example: `/task/result/60d813cd4f976942bc67bd0e` Special Points `application/json` - `200` - Data recieved - If there is no query ```javascript { data: [ { _id : __SUBMISSION_ID__, taskId : __TASK_ID__, userId : __USER_ID__, isEvaluated : __TRUE/FALSE__, grade : __1_to_5__, }, ... ] } ```` - If there is `?taskid=` query ```javascript { data: { _id : __SUBMISSION_ID__, taskId : __TASK_ID__, userId : __USER_ID__, isEvaluated : __TRUE/FALSE__, grade : __1_to_5__, } } ``` - `404` - Not found - if there is no query, no user with the userID found ```javascript { error : 'user not found', errorOccured : 'user' } ``` - if there is `?taskid=` query ```javascript { error : 'user/task not found', errorOccured : 'user/task' } ``` - `500` - Database unresponsive ```javascript { error: 'database unresponsive', errorOccured: 'database', errorMessage: __DETAILED_REPORT_FROM_MONGOOSE__ } ``` ## Models ### - User Model ```json { name :{ type : String, required : true, }, email :{ type : String, required : true, unique : true }, contact :{ type : String, required : true, }, track :{ type : String, required : true, enum : ['Beginner', 'Intermediate', 'Advanced'] }, password :{ type : String, required : true }, dor :{ type : Date, default : new Date() } } ``` ### - Instructor Model ```json { name :{ type : String, required : true, }, email :{ type : String, required : true, unique : true }, contact :{ type : String, required : true, }, password :{ type : String, required : true }, doj :{ type : Date, default : new Date() } } ``` ### - Task Model ```json { name :{ type : String, required : true }, desc :{ type : String }, imgUrl :{ type : Url, required : true }, assignedTo :{ type : [String], required : true }, deadline :{ type: Date, required : true, }, assignedBy :{ type : ObjectId, required : true } } ``` ### - Submission Model ```json { userId :{ type : ObjectId, required : true, }, taskId :{ type : ObjectId, required : true }, imgSubmitted :{ type : Url, required : true }, isEvaluated :{ type : Boolean, default : false, }, grade :{ type : Number, default : 0, enum : [1,2,3,4,5] } } ``` _______________________________ Name : Pratyay Saha Resume : [https://resume.smll.in](https://resume.smll.in)