polished doc for dataset API (infiniflow#1219)

### What problem does this PR solve? Added doc for API. ### Type of change - [x] Documentation Update
Halfknow · Jun 20, 2024 · 1975390 · 1975390
1 parent eddc4e6
commit 1975390
Showing 1 changed file with 142 additions and 13 deletions.
diff --git a/docs/references/ragflow_api.md b/docs/references/ragflow_api.md
@@ -8,7 +8,12 @@ RAGFlow offers RESTful APIs for you to integrate its capabilities into third-par
 
 ## Base URL
 ```
-https://demo.ragflow.io/api/v1/
+http://<host_address>/api/v1/
+```
+
+## Dataset URL
+```
+http://<host_address>/api/v1/dataset
 ```
 
 ## Authorization
@@ -40,7 +45,7 @@ This method creates (news) a dataset for a specific user.
 | POST   | `/dataset`  |
 
 :::note
-You are *required* to save the `data.id` value returned in the response data, which is the session ID for all upcoming conversations.
+You are *required* to save the `data.dataset_id` value returned in the response data, which is the session ID for all upcoming conversations.
 :::
 
 #### Request parameter
@@ -78,18 +83,17 @@ This method lists the created datasets for a specific user.
 
 #### Response parameter
 
-```python
-(200, 
+```json
 {
-    "code": 102,
+    "code": 0,
     "data": [
         {
-            "avatar": None,
+            "avatar": null,
             "chunk_num": 0,
             "create_date": "Mon, 17 Jun 2024 16:00:05 GMT",
             "create_time": 1718611205876,
             "created_by": "b48110a0286411ef994a3043d7ee537e",
-            "description": None,
+            "description": null,
             "doc_num": 0,
             "embd_id": "BAAI/bge-large-zh-v1.5",
             "id": "9bd6424a2c7f11ef81b83043d7ee537e",
@@ -112,12 +116,10 @@ This method lists the created datasets for a specific user.
             "update_date": "Mon, 17 Jun 2024 16:00:05 GMT",
             "update_time": 1718611205876,
             "vector_similarity_weight": 0.3
-        },
-        # ... additional datasets ...
+        }
     ],
-    "message": "attempt to list datasets"
+    "message": "List datasets successfully!"
 }
-)
 ```
 
 ## Delete dataset
@@ -142,7 +144,134 @@ This method deletes a dataset for a specific user.
 
 ```json
 {
-  "success": true, 
-  "message": "Dataset deleted successfully!"
+  "code": 0,
+  "message": "Remove dataset: 9cefaefc2e2611ef916b3043d7ee537e successfully"
 }
 ```  
+
+### Get the details of the specific dataset
+
+This method gets the details of the specific dataset. 
+
+### Request
+
+#### Request URI
+
+| Method   | Request URI             |
+|----------|-------------------------|
+| GET      | `/dataset/{dataset_id}` |
+
+#### Request parameter
+
+| Name         |  Type  | Required | Description                                                                                                                                                      |
+|--------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `dataset_id` | string | Yes      | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID.                                                                                |
+
+### Response 
+
+```json
+{
+    "code": 0,
+    "data": {
+        "avatar": null,
+        "chunk_num": 0, 
+        "description": null,
+        "doc_num": 0,
+        "embd_id": "BAAI/bge-large-zh-v1.5",
+        "id": "060323022e3511efa8263043d7ee537e", 
+        "language": "Chinese", 
+        "name": "test(1)", 
+        "parser_config": 
+        {
+            "pages": [[1, 1000000]]
+        }, 
+        "parser_id": "naive", 
+        "permission": "me", 
+        "token_num": 0
+  }, 
+    "message": "success"
+}
+```
+
+### Update the details of the specific dataset
+
+This method updates the details of the specific dataset. 
+
+### Request
+
+#### Request URI
+
+| Method | Request URI             |
+|--------|-------------------------|
+| PUT    | `/dataset/{dataset_id}` |
+
+#### Request parameter
+
+You are required to input at least one parameter.
+
+| Name                 | Type   | Required | Description                                                           |
+|----------------------|--------|----------|-----------------------------------------------------------------------|
+| `name`               | string | No       | The name of the knowledge base, from which you get the document list. |
+| `description`        | string | No       | The description of the knowledge base.                                |
+| `permission`         | string | No       | The permission for the knowledge base, default:me.                    |
+| `language`           | string | No       | The language of the knowledge base.                                   |
+| `chunk_method`       | string | No       | The chunk method of the knowledge base.                               |
+| `embedding_model_id` | string | No       | The embedding model id of the knowledge base.                         |
+| `photo`              | string | No       | The photo of the knowledge base.                                      |
+| `layout_recognize`   | bool   | No       | The layout recognize of the knowledge base.                           |
+| `token_num`          | int    | No       | The token number of the knowledge base.                               |
+| `id`                 | string | No       | The id of the knowledge base.                                         |
+
+### Response 
+
+### Successful response
+
+```json
+{
+    "code": 0,
+    "data": {
+        "avatar": null,
+        "chunk_num": 0,
+        "create_date": "Wed, 19 Jun 2024 20:33:34 GMT",
+        "create_time": 1718800414518, 
+        "created_by": "b48110a0286411ef994a3043d7ee537e", 
+        "description": "new_description1", 
+        "doc_num": 0, 
+        "embd_id": "BAAI/bge-large-zh-v1.5", 
+        "id": "24f9f17a2e3811ef820e3043d7ee537e", 
+        "language": "English", 
+        "name": "new_name", 
+        "parser_config": 
+        {
+            "pages": [[1, 1000000]]
+        },
+        "parser_id": "naive", 
+        "permission": "me", 
+        "similarity_threshold": 0.2, 
+        "status": "1", 
+        "tenant_id": "b48110a0286411ef994a3043d7ee537e", 
+        "token_num": 0, 
+        "update_date": "Wed, 19 Jun 2024 20:33:34 GMT", 
+        "update_time": 1718800414529, 
+        "vector_similarity_weight": 0.3
+  }, 
+    "message": "success"
+}
+```
+
+### Response for the operating error
+
+```json
+{
+    "code": 103, 
+    "message": "Only the owner of knowledgebase is authorized for this operation!"
+}
+```
+
+### Response for no parameter
+```json
+{ 
+    "code": 102, 
+    "message": "Please input at least one parameter that you want to update!"
+}
+```