From 57474bfa985d6dd4c22180b5bbfdbffe9f657e77 Mon Sep 17 00:00:00 2001 From: Katherine Date: Fri, 22 Nov 2024 09:50:39 +0800 Subject: [PATCH] doc: rest api (#213) * doc: rest api * doc: rest api * doc: rest api * doc: rest api --- .../handbook/data-source-rest-api/index.md | 98 +++++++++++------- .../handbook/data-source-rest-api/index.md | 99 ++++++++++++------- 2 files changed, 127 insertions(+), 70 deletions(-) diff --git a/docs/en-US/handbook/data-source-rest-api/index.md b/docs/en-US/handbook/data-source-rest-api/index.md index 2f3f221a3..a77dea210 100644 --- a/docs/en-US/handbook/data-source-rest-api/index.md +++ b/docs/en-US/handbook/data-source-rest-api/index.md @@ -84,11 +84,41 @@ Map the interface for deleting a resource. ![20240716211808](https://static-docs.nocobase.com/20240716211808.png) +Both the List and Get interfaces are required to be configured. ## Debugging the API +### Request parameter integration + +example: configure pagination parameters for the List API. + +if the third-party api does not support pagination natively, implement pagination will based on the retrieved list data. + +![20241121205229](https://static-docs.nocobase.com/20241121205229.png) + +Note: Only variables added to the API will work. + +| Third-party API params name | NocoBase params | +| --------------------------- | --------------------------- | +| page | {{request.params.page}} | +| limit | {{request.params.pageSize}} | + You can easily debug the API by clicking **Try it out**. -![20240716212722](https://static-docs.nocobase.com/20240716212722.png) +![20241121210320](https://static-docs.nocobase.com/20241121210320.png) + + + +### Response format transformation + +The response format of the third-party API may not be in NocoBase standard, and it needs to be transformed before it can be correctly displayed on the front end. + +![20241121214638](https://static-docs.nocobase.com/20241121214638.png) + +Adjust the conversion rules based on the response format of the third-party API to ensure the output conforms to the NocoBase standard. + +![20241121215100](https://static-docs.nocobase.com/20241121215100.png) ### Debugging Process Overview @@ -127,50 +157,50 @@ Below are the variables available for each interface: ### List -| Parameter | Description | -| ----------------------- | ----------------------------------------------------- | -| request.params.page | Pagination parameter | -| request.params.pageSize | Number of items per page | -| request.params.filter | Filtering conditions | -| request.params.sort | Sorting options | -| request.params.appends | Additional fields to load as needed, typically for on-demand loading of relational fields | -| request.params.fields | Specifies which fields to output (whitelist) | -| request.params.except | Specifies which fields to exclude (blacklist) | +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------- | +| request.params.page | Current page | +| request.params.pageSize | Number of items per page | +| request.params.filter | Filter criteria (must meet NocoBase Filter format) | +| request.params.sort | Sorting criteria (must meet NocoBase Sort format) | +| request.params.appends | Fields to load on demand, typically for association fields | +| request.params.fields | Fields to include (whitelist) | +| request.params.except | Fields to exclude (blacklist) | ### Get -| Parameter | Description | -| ----------------------- | ----------------------------------------------------- | -| request.params.filterByTk | Key for filtering | -| request.params.filter | Filtering conditions | -| request.params.appends | Additional fields to load as needed, typically for on-demand loading of relational fields | -| request.params.fields | Specifies which fields to output (whitelist) | -| request.params.except | Specifies which fields to exclude (blacklist) | +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------- | +| request.params.filterByTk | Required, typically the current record ID | +| request.params.filter | Filter criteria (must meet NocoBase Filter format) | +| request.params.appends | Fields to load on demand, typically for association fields | +| request.params.fields | Fields to include (whitelist) | +| request.params.except | Fields to exclude (blacklist) | ### Create -| Parameter | Description | -| ----------------------- | ----------------------------------------------------- | -| request.params.whiteList | Whitelist | -| request.params.blacklist | Blacklist | -| request.body | Initial data for creation | +| Parameter | Description | +| ------------------------ | ------------------------- | +| request.params.whiteList | Whitelist | +| request.params.blacklist | Blacklist | +| request.body | Initial data for creation | ### Update -| Parameter | Description | -| ----------------------- | ----------------------------------------------------- | -| request.params.filterByTk | Key for filtering | -| request.params.filter | Filtering conditions | -| request.params.whiteList | Whitelist | -| request.params.blacklist | Blacklist | -| request.body | Data for update | +| Parameter | Description | +| ------------------------- | -------------------------------------------------- | +| request.params.filterByTk | Required, typically the current record ID | +| request.params.filter | Filter criteria (must meet NocoBase Filter format) | +| request.params.whiteList | Whitelist | +| request.params.blacklist | Blacklist | +| request.body | Data for update | ### Destroy -| Parameter | Description | -| ----------------------- | ----------------------------------------------------- | -| request.params.filterByTk | Key for filtering | -| request.params.filter | Filtering conditions | +| Parameter | Description | +| ------------------------- | ----------------------------------------- | +| request.params.filterByTk | Required, typically the current record ID | +| request.params.filter | Filtering conditions | ## Field Configuration @@ -180,7 +210,7 @@ Field metadata (Fields) is extracted from the CRUD interface data of the adapted Field metadata extraction. -![20240716224010](https://static-docs.nocobase.com/20240716224010.png) +![20241121230436](https://static-docs.nocobase.com/20241121230436.png) Field and preview. diff --git a/docs/zh-CN/handbook/data-source-rest-api/index.md b/docs/zh-CN/handbook/data-source-rest-api/index.md index f42ccbdbf..70a42d905 100644 --- a/docs/zh-CN/handbook/data-source-rest-api/index.md +++ b/docs/zh-CN/handbook/data-source-rest-api/index.md @@ -75,7 +75,6 @@ REST API 数据源的 Collection 配置如下 ### Update 配置更新资源的接口映射 - ![20240716211733](https://static-docs.nocobase.com/20240716211733.png) ### Destroy @@ -84,11 +83,39 @@ REST API 数据源的 Collection 配置如下 ![20240716211808](https://static-docs.nocobase.com/20240716211808.png) +其中 List 和 Get 是 必须配置的两个接口。 ## 调试 API -可以点击 Try it out 进行调试 +### 请求参数对接 + +示例: 为 List 接口配置分页参数（如果第三方 API 本身不支持分页，则以取到的列表数据来分页）。 + +![20241121205229](https://static-docs.nocobase.com/20241121205229.png) + +请注意，只有在接口中已添加的变量才会生效。 + +| 第三方 API 接入参数名 | NocoBase 参数 | +| --------------------- | --------------------------- | +| page | {{request.params.page}} | +| limit | {{request.params.pageSize}} | + +可以点击 Try it out 进行调试，查看响应结果。 + +![20241121210320](https://static-docs.nocobase.com/20241121210320.png) + + + +### 响应格式转换 + +第三方 API 的响应格式可能并不是 NocoBase 标准，需要转换之后才能正确的在前端显示。 + +![20241121214638](https://static-docs.nocobase.com/20241121214638.png) + +根据第三方 API 的响应格式调整转换规则，使其符合 NocoBase 输出标准。 -![20240716212722](https://static-docs.nocobase.com/20240716212722.png) +![20241121215100](https://static-docs.nocobase.com/20241121215100.png) 调试流程说明 @@ -127,50 +154,50 @@ REST API 数据源提供了三类变量用于接口的对接 ### List -| 参数 | 说明 | -| -- | -- | -| request.params.page | 分页参数 | -| request.params.pageSize | 每页显示数量 | -| request.params.filter | 条件过滤 | -| request.params.sort | 排序 | -| request.params.appends | 按需加载的字段，一般用于关系字段的按需加载 | -| request.params.fields | 接口只输出哪些字段（白名单） | -| request.params.except | 排除哪些字段（黑名单） | +| 参数 | 说明 | +| ----------------------- | -------------------------------------------- | +| request.params.page | 当前页数 | +| request.params.pageSize | 每页数量 | +| request.params.filter | 过滤条件（需要符合 NocoBase 的 Filter 格式） | +| request.params.sort | 排序规则（需要符合 NocoBase 的 Sort 格式） | +| request.params.appends | 按需加载的字段，一般用于关系字段的按需加载 | +| request.params.fields | 接口只输出哪些字段（白名单） | +| request.params.except | 排除哪些字段（黑名单） | ### Get -| 参数 | 说明 | -| -- | -- | -| request.params.filterByTk | 每页显示数量 | -| request.params.filter | 条件过滤 | -| request.params.appends | 按需加载的字段，一般用于关系字段的按需加载 | -| request.params.fields | 接口只输出哪些字段（白名单） | -| request.params.except | 排除哪些字段（黑名单） | +| 参数 | 说明 | +| ------------------------- | -------------------------------------------- | +| request.params.filterByTk | 必填，一般为当前数据的 ID | +| request.params.filter | 过滤条件（需要符合 NocoBase 的 Filter 格式） | +| request.params.appends | 按需加载的字段，一般用于关系字段的按需加载 | +| request.params.fields | 接口只输出哪些字段（白名单） | +| request.params.except | 排除哪些字段（黑名单） | ### Create -| 参数 | 说明 | -| -- | -- | -| request.params.whiteList | 白名单 | -| request.params.blacklist | 黑名单 | -| request.body | 创建的初始化数据 | +| 参数 | 说明 | +| ------------------------ | ---------------- | +| request.params.whiteList | 白名单 | +| request.params.blacklist | 黑名单 | +| request.body | 创建的初始化数据 | ### Update -| 参数 | 说明 | -| -- | -- | -| request.params.filterByTk | 每页显示数量 | -| request.params.filter | 条件过滤 | -| request.params.whiteList | 白名单 | -| request.params.blacklist | 黑名单 | -| request.body | 更新的数据 | +| 参数 | 说明 | +| ------------------------- | -------------------------------------------- | +| request.params.filterByTk | 必填，一般为当前数据的 ID | +| request.params.filter | 过滤条件（需要符合 NocoBase 的 Filter 格式） | +| request.params.whiteList | 白名单 | +| request.params.blacklist | 黑名单 | +| request.body | 更新的数据 | ### Destroy -| 参数 | 说明 | -| -- | -- | -| request.params.filterByTk | 每页显示数量 | -| request.params.filter | 条件过滤 | +| 参数 | 说明 | +| ------------------------- | -------------------------------------------- | +| request.params.filterByTk | 必填，一般为当前数据的 ID | +| request.params.filter | 过滤条件（需要符合 NocoBase 的 Filter 格式） | ## 配置字段 @@ -180,7 +207,7 @@ REST API 数据源提供了三类变量用于接口的对接 提取字段元数据 -![20240716224010](https://static-docs.nocobase.com/20240716224010.png) +![20241121230436](https://static-docs.nocobase.com/20241121230436.png) 字段及预览