From 533f0f28c5c6df93a82a1e612afa07af90627c63 Mon Sep 17 00:00:00 2001 From: raynerljm Date: Thu, 9 Nov 2023 16:23:42 +0800 Subject: [PATCH] docs: make change to trigger workflow --- backend/api-gateway/README.md | 2 +- backend/collaboration-service/README.md | 2 +- backend/matching-service/README.md | 16 + backend/question-service/server/app/readme.md | 402 +++++++++--------- backend/user-service/README.md | 2 +- frontend/README.md | 2 +- 6 files changed, 221 insertions(+), 205 deletions(-) create mode 100644 backend/matching-service/README.md diff --git a/backend/api-gateway/README.md b/backend/api-gateway/README.md index 770490d89..982199bcf 100644 --- a/backend/api-gateway/README.md +++ b/backend/api-gateway/README.md @@ -2,7 +2,7 @@ ## Instructions to run -- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the API gateway service +- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the API gateway service. ## Making requests to the API gateway for inter-service communicatio diff --git a/backend/collaboration-service/README.md b/backend/collaboration-service/README.md index 0fcb21dd8..34cc0aaab 100644 --- a/backend/collaboration-service/README.md +++ b/backend/collaboration-service/README.md @@ -13,4 +13,4 @@ If you need to add new environment variables, please add them to the following l 1. If the value is a secret, leave it blank and store it with the team's vault (e.g. an API key, secret key, access token, ARN, etc.) 2. If the value is not a secret, you can leave in the value in the `.env.example` file (e.g. http://localhost:8000, staging, 32, etc.) -2. `/backend/collaboration-service/infra/index.ts` under the `Deploy an ECS Service on Fargate to host the application container` comment under the `env` object. For Pulumi to inject the appropriate environment variables during deployment. \ No newline at end of file +2. `/backend/collaboration-service/infra/index.ts` under the `Deploy an ECS Service on Fargate to host the application container` comment under the `env` object. For Pulumi to inject the appropriate environment variables during deployment. diff --git a/backend/matching-service/README.md b/backend/matching-service/README.md new file mode 100644 index 000000000..25f33e62a --- /dev/null +++ b/backend/matching-service/README.md @@ -0,0 +1,16 @@ +# Matching Service + +## Instructions to run + +- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the matching service + +## New environment variables + +If you need to add new environment variables, please add them to the following locations: + +1. `/backend/matching-service/app/.env.example` file and commit it. For others to run the service locally. + + 1. If the value is a secret, leave it blank and store it with the team's vault (e.g. an API key, secret key, access token, ARN, etc.) + 2. If the value is not a secret, you can leave in the value in the `.env.example` file (e.g. http://localhost:8000, staging, 32, etc.) + +2. `/backend/matching-service/infra/index.ts` under the `Deploy an ECS Service on Fargate to host the application container` comment under the `env` object. For Pulumi to inject the appropriate environment variables during deployment. diff --git a/backend/question-service/server/app/readme.md b/backend/question-service/server/app/readme.md index 3f4d843a5..c23d69028 100644 --- a/backend/question-service/server/app/readme.md +++ b/backend/question-service/server/app/readme.md @@ -62,61 +62,61 @@ docker run -p 8000:80 question-service 1. `GET /api/questions` Get Questions by Criteria - - **Description**: Returns a list of questions (ids and titles) matching the given criteria: Difficulty and Topic. - - **Query Parameters**: - - `difficulty`: List of difficulties to filter by (e.g., `["Easy", "Medium"]`). Optional. - - `topic`: List of topics to filter by (e.g., `["Arrays", "Strings"]`). Optional. - - **Multiple values can be provided, in which case all questions that satisfy at least one difficulty and one topic will appear.** - - **Sample Request**: - - ``` - GET /api/questions # Returns all questions (no filters) - ``` - - ``` - GET /api/questions?difficulty=Easy&topic=Arrays # Returns all Easy questions with topic Arrays - ``` - - ``` - GET /api/questions?difficulty=Easy&difficulty=Medium&topic=Hash%20Tables&topic=Arrays # Returns all Easy or Medium questions with topic Hash Tables or Arrays - ``` - - **Sample Response**: - - ```json - { - "status": "success", - "data": { - "questions": [ - { - "id": "1", - "title": "Find Maximum in Array", - ... - }, - { - "id": "2", - "title": "Reverse Array", - ... - } - ] - } - } - ``` + - **Description**: Returns a list of questions (ids and titles) matching the given criteria: Difficulty and Topic. + - **Query Parameters**: + - `difficulty`: List of difficulties to filter by (e.g., `["Easy", "Medium"]`). Optional. + - `topic`: List of topics to filter by (e.g., `["Arrays", "Strings"]`). Optional. + - **Multiple values can be provided, in which case all questions that satisfy at least one difficulty and one topic will appear.** + + **Sample Request**: + + ``` + GET /api/questions # Returns all questions (no filters) + ``` + + ``` + GET /api/questions?difficulty=Easy&topic=Arrays # Returns all Easy questions with topic Arrays + ``` + + ``` + GET /api/questions?difficulty=Easy&difficulty=Medium&topic=Hash%20Tables&topic=Arrays # Returns all Easy or Medium questions with topic Hash Tables or Arrays + ``` + + **Sample Response**: + + ```json + { + "status": "success", + "data": { + "questions": [ + { + "id": "1", + "title": "Find Maximum in Array", + ... + }, + { + "id": "2", + "title": "Reverse Array", + ... + } + ] + } + } + ``` 2. `GET /api/questions/view` Retrieve Questions with Pagination, Filtering and Sorting - - **Description**: Retrieve questions with optional sorting and pagination. Used for question portal view. - - **Query Parameters**: - - `page`: Page number for pagination. Starts from 0. Default is 0. - - `limit`: Number of items to retrieve per page. Default is 10. - - `sort_by`: Field to sort by (e.g., `title`). Default is `id`. - - `order`: Order of sorting. Use 'asc' for ascending and 'desc' for descending. Default is `asc`. - - `difficulty` (list of strings, optional): Allows users to filter questions by their difficulty levels. Accepts a list of difficulty values. - - `topic` (list of strings, optional): Enables users to filter questions based on specific topics. - - `category` (list of strings, optional): Lets users filter questions by their categories. - - `paid_only` (boolean, optional): When set to `true`, only questions that are paid will be returned. When set to `false`, only free questions will be returned. - - `search` (string, optional): A search string that will be used to match questions. Questions with titles or descriptions that contain the search string will be returned. + - **Description**: Retrieve questions with optional sorting and pagination. Used for question portal view. + - **Query Parameters**: + - `page`: Page number for pagination. Starts from 0. Default is 0. + - `limit`: Number of items to retrieve per page. Default is 10. + - `sort_by`: Field to sort by (e.g., `title`). Default is `id`. + - `order`: Order of sorting. Use 'asc' for ascending and 'desc' for descending. Default is `asc`. + - `difficulty` (list of strings, optional): Allows users to filter questions by their difficulty levels. Accepts a list of difficulty values. + - `topic` (list of strings, optional): Enables users to filter questions based on specific topics. + - `category` (list of strings, optional): Lets users filter questions by their categories. + - `paid_only` (boolean, optional): When set to `true`, only questions that are paid will be returned. When set to `false`, only free questions will be returned. + - `search` (string, optional): A search string that will be used to match questions. Questions with titles or descriptions that contain the search string will be returned. **Sample Request**: @@ -166,179 +166,179 @@ GET /api/questions/view?page=1&limit=5&sort_by=title&order=desc&difficulty=Easy& 3. `GET /api/questions/all` Get All Questions - - **Description**: Returns a list of all questions with all fields. - - **Sample Request**: - - ``` - GET /api/questions/all - ``` - - **Sample Response**: - - ```json - { - "status": "success", - "data": { - "questions": [ - { - "id": "1", - "title": "Find Maximum in Array", - "difficulty": "Easy", - "topic_tags": ["Arrays"], - ... - }, - { - "id": "2", - "title": "Reverse Array", - "difficulty": "Easy", - "topic_tags": ["Arrays"], - ... - } - ] - } - } - ``` + - **Description**: Returns a list of all questions with all fields. + + **Sample Request**: + + ``` + GET /api/questions/all + ``` + + **Sample Response**: + + ```json + { + "status": "success", + "data": { + "questions": [ + { + "id": "1", + "title": "Find Maximum in Array", + "difficulty": "Easy", + "topic_tags": ["Arrays"], + ... + }, + { + "id": "2", + "title": "Reverse Array", + "difficulty": "Easy", + "topic_tags": ["Arrays"], + ... + } + ] + } + } + ``` 4. `GET /api/questions/{question_id}` Get a Single Question - - **Description**: Returns a single question matching the given id. - - **Path Parameters**: - - `question_id`: The integer ID of the question to retrieve. Required. - - **Sample Request**: - - ``` - GET /api/questions/1 - ``` - - **Sample Response**: - - ```json - { - "status": "success", - "data": { - "question": { - "id": "1", - "title": "Find Maximum in Array", - "difficulty": "Easy", - "topic_tags": ["Arrays"], - ... - } - } - } - ``` + - **Description**: Returns a single question matching the given id. + - **Path Parameters**: + - `question_id`: The integer ID of the question to retrieve. Required. + + **Sample Request**: + + ``` + GET /api/questions/1 + ``` + + **Sample Response**: + + ```json + { + "status": "success", + "data": { + "question": { + "id": "1", + "title": "Find Maximum in Array", + "difficulty": "Easy", + "topic_tags": ["Arrays"], + ... + } + } + } + ``` 5. `GET /api/questions/filters` Get Question Filters - - **Description**: Returns a list of all possible filters for questions: Difficulty and Topic. + - **Description**: Returns a list of all possible filters for questions: Difficulty and Topic. - **Sample Request**: + **Sample Request**: - ``` - GET /api/questions/filters - ``` + ``` + GET /api/questions/filters + ``` - **Sample Response**: + **Sample Response**: - ```json - { - "status": "success", - "data": { - "Easy": ["Arrays", "Strings"], - "Medium": ["Trees", "Graphs"], - "Hard": ["Dynamic Programming", "Recursion"] - } - } - ``` + ```json + { + "status": "success", + "data": { + "Easy": ["Arrays", "Strings"], + "Medium": ["Trees", "Graphs"], + "Hard": ["Dynamic Programming", "Recursion"] + } + } + ``` ### `/api/admin` Endpoints 1. `POST /api/admin/questions` Create a New Question - - **Description**: Creates a new question in the database. - - **Request Body**: - - `question`: The question data in JSON format. **If no ID is provided, one will automatically be generated.** - - **Sample Request**: - - ```json - POST /api/admin/questions - { - "title": "New Question Title", - "difficulty": "Easy", - "topic_tags": ["Arrays"], - ... - } - ``` - - **Sample Response**: - - ```json - { - "status": "success", - "data": { - "question": { - "id": "123", - "title": "New Question Title", - ... - } - } - } - ``` + - **Description**: Creates a new question in the database. + - **Request Body**: + - `question`: The question data in JSON format. **If no ID is provided, one will automatically be generated.** + + **Sample Request**: + + ```json + POST /api/admin/questions + { + "title": "New Question Title", + "difficulty": "Easy", + "topic_tags": ["Arrays"], + ... + } + ``` + + **Sample Response**: + + ```json + { + "status": "success", + "data": { + "question": { + "id": "123", + "title": "New Question Title", + ... + } + } + } + ``` 2. `PUT /api/admin/questions/{question_id}` Update an Existing Question - - **Description**: Updates an existing question in the database. - - **Path Parameters**: - - `question_id`: The ID of the question to update. - - **Request Body**: - - `updated_data`: The updated question data in JSON format. **Only fields specified in the request body will be updated.** - - **Sample Request**: - - ```json - PUT /api/admin/questions/123 - { - "title": "Updated Question Title", # Only title will be updated - } - ``` - - **Sample Response**: - - ```json - { - "status": "success", - "data": { - "updated_id": "123", - "updated_data": { - "title": "Updated Question Title", # Response indicates that only title was updated - } - } - } - ``` + - **Description**: Updates an existing question in the database. + - **Path Parameters**: + - `question_id`: The ID of the question to update. + - **Request Body**: + - `updated_data`: The updated question data in JSON format. **Only fields specified in the request body will be updated.** + + **Sample Request**: + + ```json + PUT /api/admin/questions/123 + { + "title": "Updated Question Title", # Only title will be updated + } + ``` + + **Sample Response**: + + ```json + { + "status": "success", + "data": { + "updated_id": "123", + "updated_data": { + "title": "Updated Question Title", # Response indicates that only title was updated + } + } + } + ``` 3. `DELETE /api/admin/questions/{question_id}` Delete a Question - - **Description**: Deletes a question from the database. - - **Path Parameters**: - - `question_id`: The ID of the question to delete. Required. + - **Description**: Deletes a question from the database. + - **Path Parameters**: + - `question_id`: The ID of the question to delete. Required. - **Sample Request**: + **Sample Request**: - ``` - DELETE /api/admin/questions/123 - ``` + ``` + DELETE /api/admin/questions/123 + ``` - **Sample Response**: + **Sample Response**: - ```json - { - "status": "success", - "data": { - "deleted_id": "123" - } - } - ``` + ```json + { + "status": "success", + "data": { + "deleted_id": "123" + } + } + ``` --- diff --git a/backend/user-service/README.md b/backend/user-service/README.md index 3c3c1dd6e..e0f139228 100644 --- a/backend/user-service/README.md +++ b/backend/user-service/README.md @@ -2,7 +2,7 @@ ## Instructions to run -- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the User service +- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the User service. ## New environment variables diff --git a/frontend/README.md b/frontend/README.md index 9bb2473a3..030e67dd4 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -2,7 +2,7 @@ ## Instructions to run -- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the frontend service +- Please refer to the [README.md](../README.md) in the root of the project for instructions to run the frontend service. ## New environment variables