Skip to content

Commit

Permalink
doc: rest api (#213)
Browse files Browse the repository at this point in the history 
* doc: rest api

* doc: rest api

* doc: rest api

* doc: rest api
  • Loading branch information
@katherinehhh
katherinehhh authored Nov 22, 2024
1 parent 3a84a24 commit 57474bf
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 70 deletions.
98 changes: 64 additions & 34 deletions docs/en-US/handbook/data-source-rest-api/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<video width="100%" height="440" controls>
<source src="https://static-docs.nocobase.com/20241121211034.mp4" type="video/mp4">
</video>

### 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

Expand Down Expand Up @@ -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

Expand All @@ -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.

Expand Down
99 changes: 63 additions & 36 deletions docs/zh-CN/handbook/data-source-rest-api/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,6 @@ REST API 数据源的 Collection 配置如下
### Update

配置更新资源的接口映射

![20240716211733](https://static-docs.nocobase.com/20240716211733.png)

### Destroy
Expand All @@ -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)

<video width="100%" height="440" controls>
<source src="https://static-docs.nocobase.com/20241121211034.mp4" type="video/mp4">
</video>

### 响应格式转换

第三方 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)

调试流程说明

Expand Down Expand Up @@ -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 格式） |

## 配置字段

Expand All @@ -180,7 +207,7 @@ REST API 数据源提供了三类变量用于接口的对接

提取字段元数据

![20240716224010](https://static-docs.nocobase.com/20240716224010.png)
![20241121230436](https://static-docs.nocobase.com/20241121230436.png)

字段及预览

Expand Down

0 comments on commit 57474bf

Please sign in to comment.