From efcce6a8261065d816d901c677e08f34a396869d Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Mon, 16 Oct 2023 14:51:24 +0000 Subject: [PATCH 1/6] Enhancement: Improve API Endpoint Documentation --- docs/pages/Developing/API-docs.md | 83 ++++++++++++++++++++++--------- 1 file changed, 59 insertions(+), 24 deletions(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index 2d832845..61428188 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -1,9 +1,22 @@ -Currently, the application provides the following main API endpoints: +*Currently, the application provides the following main API endpoints:* + +# API Endpoints Documentation ### /api/answer -It's a POST request that sends a JSON in body with 4 values. It will receive an answer for a user provided question. -Here is a JavaScript fetch example: +**Description:**: +This endpoint is used to request answers to user-provided questions. +**Request:** +Method: POST +Headers: Content-Type should be set to "application/json; charset=utf-8" +Request Body: JSON object with the following fields: +* **question:** The user's question +* **history:** (Optional) Previous conversation history +* **api_key:** Your API key +* **embeddings_key:** Your embeddings key +* **active_docs:** The location of active documentation + +Here is a JavaScript Fetch Request example: ```js // answer (POST http://127.0.0.1:5000/api/answer) fetch("http://127.0.0.1:5000/api/answer", { @@ -17,9 +30,8 @@ fetch("http://127.0.0.1:5000/api/answer", { .then((res) => res.text()) .then(console.log.bind(console)) ``` - -In response, you will get a JSON document like this one: - +**Response** +In response, you will get a JSON document containing the answer,query and the result: ```json { "answer": " Hi there! How can I help you?\n", @@ -29,9 +41,13 @@ In response, you will get a JSON document like this one: ``` ### /api/docs_check -It will make sure documentation is loaded on a server (just run it every time user is switching between libraries (documentations)). -It's a POST request that sends a JSON in a body with 1 value. Here is a JavaScript fetch example: +**Description:** +This endpoint will make sure documentation is loaded on the server (just run it every time user is switching between libraries (documentations)). +**Request:** +Headers: Content-Type should be set to "application/json; charset=utf-8" +Request Body: JSON object with the field: +* **docs:** The location of the documentation ```js // answer (POST http://127.0.0.1:5000/api/docs_check) fetch("http://127.0.0.1:5000/api/docs_check", { @@ -45,7 +61,8 @@ fetch("http://127.0.0.1:5000/api/docs_check", { .then(console.log.bind(console)) ``` -In response, you will get a JSON document like this one: +**Response:** +In response, you will get a JSON document like this one indicating whether the documentation exists or not.: ```json { "status": "exists" @@ -54,8 +71,13 @@ In response, you will get a JSON document like this one: ### /api/combine -Provides JSON that tells UI which vectors are available and where they are located with a simple get request. +**Description:** +This endpoint provides information about available vectors and their locations with a simple GET request. +**Request:** +Method: GET + +**Response:** Response will include: `date`, `description`, `docLink`, `fullName`, `language`, `location` (local or docshub), `model`, `name`, `version`. @@ -64,7 +86,13 @@ Example of JSON in Docshub and local: ### /api/upload -Uploads file that needs to be trained, response is JSON with task ID, which can be used to check on task's progress +**Description:** +This endpoint is used to upload a file that needs to be trained, response is JSON with task ID, which can be used to check on task's progress. + +**Request:** +Method: POST +Request Body: A multipart/form-data form with file upload and additional fields, including "user" and "name." + HTML example: ```html @@ -79,20 +107,23 @@ HTML example: ``` -Response: -```json -{ - "status": "ok", - "task_id": "b2684988-9047-428b-bd47-08518679103c" -} +**Response:** +This endpoint is used to get the JSON response with a status and a task ID that can be used to check the task's progress. + -``` ### /api/task_status -Gets task status (`task_id`) from `/api/upload`: +**Description:** +This endpoint is used to get the status of a task (`task_id`) from `/api/upload` + +**Request:** +Method: GET +Query Parameter: task_id (task ID to check) + +**Sample JavaScript Fetch Request:** ```js // Task status (Get http://127.0.0.1:5000/api/task_status) -fetch("http://localhost:5001/api/task_status?task_id=b2d2a0f4-387c-44fd-a443-e4fe2e7454d1", { +fetch("http://localhost:5001/api/task_status?task_id=YOUR_TASK_ID", { "method": "GET", "headers": { "Content-Type": "application/json; charset=utf-8" @@ -102,7 +133,7 @@ fetch("http://localhost:5001/api/task_status?task_id=b2d2a0f4-387c-44fd-a443-e4f .then(console.log.bind(console)) ``` -Responses: +**Responses:** There are two types of responses: 1. While the task is still running, the 'current' value will show progress from 0 to 100. @@ -135,8 +166,11 @@ There are two types of responses: ``` ### /api/delete_old -Deletes old Vector Stores: +**Description:** +This endpoint is used to delete old Vector Stores. +**Request:** +Method: GET ```js // Task status (GET http://127.0.0.1:5000/api/docs_check) fetch("http://localhost:5001/api/task_status?task_id=b2d2a0f4-387c-44fd-a443-e4fe2e7454d1", { @@ -148,8 +182,9 @@ fetch("http://localhost:5001/api/task_status?task_id=b2d2a0f4-387c-44fd-a443-e4f .then((res) => res.text()) .then(console.log.bind(console)) -Response: - +``` +**Response:** +JSON response indicating the status of the operation. ```json { "status": "ok" } ``` From 1c0b68f0e326f4a89b8bc2e05338f6b173232013 Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Mon, 16 Oct 2023 20:27:09 +0530 Subject: [PATCH 2/6] Update API-docs.md --- docs/pages/Developing/API-docs.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index 61428188..9ef964fe 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -108,8 +108,7 @@ HTML example: ``` **Response:** -This endpoint is used to get the JSON response with a status and a task ID that can be used to check the task's progress. - +JSON response with a status and a task ID that can be used to check the task's progress. ### /api/task_status @@ -133,7 +132,7 @@ fetch("http://localhost:5001/api/task_status?task_id=YOUR_TASK_ID", { .then(console.log.bind(console)) ``` -**Responses:** +**Response:** There are two types of responses: 1. While the task is still running, the 'current' value will show progress from 0 to 100. From 06cc4b07ab58684045537f647e4f22b8fa270626 Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Mon, 16 Oct 2023 20:35:17 +0530 Subject: [PATCH 3/6] Update API-docs.md --- docs/pages/Developing/API-docs.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index 9ef964fe..9007f48e 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -3,10 +3,12 @@ # API Endpoints Documentation ### /api/answer -**Description:**: +**Description:** + This endpoint is used to request answers to user-provided questions. **Request:** + Method: POST Headers: Content-Type should be set to "application/json; charset=utf-8" Request Body: JSON object with the following fields: @@ -30,7 +32,9 @@ fetch("http://127.0.0.1:5000/api/answer", { .then((res) => res.text()) .then(console.log.bind(console)) ``` + **Response** + In response, you will get a JSON document containing the answer,query and the result: ```json { @@ -41,10 +45,13 @@ In response, you will get a JSON document containing the answer,query and the re ``` ### /api/docs_check + **Description:** + This endpoint will make sure documentation is loaded on the server (just run it every time user is switching between libraries (documentations)). **Request:** + Headers: Content-Type should be set to "application/json; charset=utf-8" Request Body: JSON object with the field: * **docs:** The location of the documentation @@ -62,6 +69,7 @@ fetch("http://127.0.0.1:5000/api/docs_check", { ``` **Response:** + In response, you will get a JSON document like this one indicating whether the documentation exists or not.: ```json { @@ -72,24 +80,31 @@ In response, you will get a JSON document like this one indicating whether the d ### /api/combine **Description:** + This endpoint provides information about available vectors and their locations with a simple GET request. **Request:** + Method: GET **Response:** + Response will include: `date`, `description`, `docLink`, `fullName`, `language`, `location` (local or docshub), `model`, `name`, `version`. + Example of JSON in Docshub and local: + image ### /api/upload **Description:** + This endpoint is used to upload a file that needs to be trained, response is JSON with task ID, which can be used to check on task's progress. **Request:** + Method: POST Request Body: A multipart/form-data form with file upload and additional fields, including "user" and "name." @@ -108,11 +123,13 @@ HTML example: ``` **Response:** + JSON response with a status and a task ID that can be used to check the task's progress. ### /api/task_status **Description:** + This endpoint is used to get the status of a task (`task_id`) from `/api/upload` **Request:** @@ -133,6 +150,7 @@ fetch("http://localhost:5001/api/task_status?task_id=YOUR_TASK_ID", { ``` **Response:** + There are two types of responses: 1. While the task is still running, the 'current' value will show progress from 0 to 100. @@ -166,9 +184,11 @@ There are two types of responses: ### /api/delete_old **Description:** + This endpoint is used to delete old Vector Stores. **Request:** + Method: GET ```js // Task status (GET http://127.0.0.1:5000/api/docs_check) @@ -183,6 +203,7 @@ fetch("http://localhost:5001/api/task_status?task_id=b2d2a0f4-387c-44fd-a443-e4f ``` **Response:** + JSON response indicating the status of the operation. ```json { "status": "ok" } From a9fb61bbd6854b4ccc7d778263ce84e726f7a26c Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Tue, 17 Oct 2023 08:28:13 +0530 Subject: [PATCH 4/6] Update API-docs.md --- docs/pages/Developing/API-docs.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index 9007f48e..1f9626ec 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -2,7 +2,7 @@ # API Endpoints Documentation -### /api/answer +### 1. /api/answer **Description:** This endpoint is used to request answers to user-provided questions. @@ -44,7 +44,7 @@ In response, you will get a JSON document containing the answer,query and the re } ``` -### /api/docs_check +### 2. /api/docs_check **Description:** @@ -78,7 +78,7 @@ In response, you will get a JSON document like this one indicating whether the d ``` -### /api/combine +### 3. /api/combine **Description:** This endpoint provides information about available vectors and their locations with a simple GET request. @@ -127,7 +127,7 @@ HTML example: JSON response with a status and a task ID that can be used to check the task's progress. -### /api/task_status +### 4. /api/task_status **Description:** This endpoint is used to get the status of a task (`task_id`) from `/api/upload` @@ -182,7 +182,7 @@ There are two types of responses: } ``` -### /api/delete_old +### 5. /api/delete_old **Description:** This endpoint is used to delete old Vector Stores. From 186f565b99915966ac95c7da882992da37e33ba9 Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Tue, 17 Oct 2023 12:27:38 +0530 Subject: [PATCH 5/6] Update API-docs.md --- docs/pages/Developing/API-docs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index 1f9626ec..fd01096b 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -98,7 +98,7 @@ Example of JSON in Docshub and local: image -### /api/upload +### 4. /api/upload **Description:** This endpoint is used to upload a file that needs to be trained, response is JSON with task ID, which can be used to check on task's progress. @@ -127,7 +127,7 @@ HTML example: JSON response with a status and a task ID that can be used to check the task's progress. -### 4. /api/task_status +### 5. /api/task_status **Description:** This endpoint is used to get the status of a task (`task_id`) from `/api/upload` @@ -182,7 +182,7 @@ There are two types of responses: } ``` -### 5. /api/delete_old +### 6. /api/delete_old **Description:** This endpoint is used to delete old Vector Stores. From 062f3256a7cee1e70c5334cee40be6dc569fcc13 Mon Sep 17 00:00:00 2001 From: Rahul Kumar <104289350+rahul0x00@users.noreply.github.com> Date: Tue, 17 Oct 2023 12:28:50 +0530 Subject: [PATCH 6/6] Update API-docs.md --- docs/pages/Developing/API-docs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pages/Developing/API-docs.md b/docs/pages/Developing/API-docs.md index fd01096b..09e4f875 100644 --- a/docs/pages/Developing/API-docs.md +++ b/docs/pages/Developing/API-docs.md @@ -1,6 +1,7 @@ +# API Endpoints Documentation + *Currently, the application provides the following main API endpoints:* -# API Endpoints Documentation ### 1. /api/answer **Description:**