ruiling/tachybase_todo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update index.md

Browse Source
This commit is contained in:
Pearl C 2022-12-23 17:16:46 +08:00 committed by GitHub
parent c1b62f843e
commit 7ff1d0a2d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
docs/en-US/api/http/index.md
View File

@ -1,10 +1,10 @@
# Overview # Overview
NocoBase HTTP API is designed based on Resource & Action, it is a superset of REST API. The operation is not limited to add, delete, change, and check, Resource Action can be extended arbitrarily in NocoBase. HTTP API of NocoBase is designed based on Resource & Action, a superset of REST API. The operation includes but not limited to create, read, update and delete. Resource Action can be extended arbitrarily in NocoBase.
## Resource ## Resource
Resource has two expressions in NocoBase. Resource has two expressions in NocoBase:
- `<collection>` - `<collection>`
- `<collection>.<association>` - `<collection>.<association>`
@ -12,7 +12,7 @@ Resource has two expressions in NocoBase.
<Alert> <Alert>
- collection is the set of all abstract data - collection is the set of all abstract data
- association is the association data for the collection - association is the associated data of collection
- resource includes both collection and collection.association - resource includes both collection and collection.association
</Alert> </Alert>
@ -25,12 +25,12 @@ Resource has two expressions in NocoBase.
## Action ## Action
Representing resource operations as `:<action>` Resource action is expressed by `:<action>`
- `<collection>:<action>` - `<collection>:<action>`
- `<collection>.<association>:<action>` - `<collection>.<association>:<action>`
Built-in global operations for collection or association Built-in global actions for collection or association
- `create` - `create`
- `get` - `get`
@ -39,7 +39,7 @@ Built-in global operations for collection or association
- `destroy` - `destroy`
- `move` - `move`
Built-in association operation for association only Built-in association actions for association only
- `set` - `set`
- `add` - `add`
@ -48,9 +48,9 @@ Built-in association operation for association only
### Example ### Example
- `posts:create` Create posts - `posts:create` Create post
- `posts.user:get` View posts user - `posts.user:get` View post user
- `posts.tags:add` Attach post tags (associate existing tags with post) - `posts.tags:add` Attach tags to post (associate existing tags with post)
## Request URL ## Request URL
@ -95,45 +95,45 @@ POST /api/posts/1/tags:add
GET /api/posts/1/tags:remove GET /api/posts/1/tags:remove
``` ```
## Resource location ## Locate Resource
- collection resource, locates the data to be processed by `collectionIndex`, `collectionIndex` must be unique - collection resource locates the data to be processed by `collectionIndex`, `collectionIndex` must be unique
- association resource, locates the data to be processed by `collectionIndex` and `associationIndex` jointly, `associationIndex` may not be unique, but `collectionIndex` and `associationIndex`'s association indexes must be unique - association resource locates the data to be processed by `collectionIndex` and `associationIndex` jointly, `associationIndex` may not be unique, but the joint index of `collectionIndex` and `associationIndex` must be unique
When viewing association resource details, the requested URL needs to provide both `<collectionIndex>` and `<associationIndex>`, `<collectionIndex>` is not redundant because `<associationIndex>` may not be unique. When viewing details of association resource, the requested URL needs to provide both `<collectionIndex>` and `<associationIndex>`, `<collectionIndex>` is needed as `<associationIndex>` may not be unique.
For example, `tables.fields` indicates the fields of a data table For example, `tables.fields` represents the fields of a data table:
```bash ```bash
GET /api/tables/table1/fields/title GET /api/tables/table1/fields/title
GET /api/tables/table2/fields/title GET /api/tables/table2/fields/title
``` ```
Both table1 and table2 have a title field. The title is unique in table1, but other tables may also have a title field Both table1 and table2 have the title field, title is unique in one table, but other tables may also have fields of that name.
## Request parameters ## Request Parameters
Request parameters can be placed in the request's headers, parameters (query string), and body (GET requests do not have a body). Request parameters can be placed in the headers, parameters (query string), and body (GET requests do not have a body) of the request.
A few special request parameters Some special request parameters:
- `filter` Data filtering, used in query-related operations. - `filter` Data filtering, used in actions related to query.
- `filterByTk` filter by tk field, used in operations that specify details of the data. - `filterByTk` Filter by tk field, used in actions to specify details of data.
- `sort` Sorting, used in query-related operations. - `sort` Sorting, used in actions related to query.
- `fields` which data to output, for use in query-related operations. - `fields` Date to output, used in actions related to query
- `appends` additional relationship fields for use in query-related operations. - `appends` Fields of additional relationship, used in actions related to query.
- `except` which fields to exclude (no output), used in query-related operations. - `except` Exclude some fields (not to output), used in actions related to query.
- `whitelist` fields whitelist, used in data creation and update related operations. - `whitelist` Fields whitelist, used in actions related to data creation and update.
- `blacklist` fields blacklist, used in data creation and update related operations. - `blacklist` Fields blacklist, used in actions related to data creation and update.
### filter ### filter
Data filter Data filtering.
```bash ```bash
# simple # simple
GET /api/posts?filter[status]=publish GET /api/posts?filter[status]=publish
# Recommend using the json string format, which requires encodeURIComponent encoding # json string format is recommended, which requires encodeURIComponent encoding
GET /api/posts?filter={"status":"published"} GET /api/posts?filter={"status":"published"}
# filter operators # filter operators
@ -154,10 +154,10 @@ GET /api/posts?filter={"user.email.$includes":"gmail"}
### filterByTk ### filterByTk
Filter by tk field. By default Filter by tk field. In the default settings:
- collection resource, tk is the primary key of the data table. - collection resource: tk is the primary key of the data table.
- association resource, tk is the targetKey field of the association. - association resource: tk is the targetKey field of the association.
```bash ```bash
GET /api/posts:get?filterByTk=1&fields=name,title&appends=tags GET /api/posts:get?filterByTk=1&fields=name,title&appends=tags
@ -165,20 +165,20 @@ GET /api/posts:get?filterByTk=1&fields=name,title&appends=tags
### sort ### sort
Sorting. When sorting in descending order, the fields are preceded by the minus sign `-`. Sorting. To sort in the descending order, put `-` in front of the field.
```bash ```bash
# createAt field in ascending order # Sort createAt field in the ascending order
GET /api/posts:get?sort=createdAt GET /api/posts:get?sort=createdAt
# createAt field descending # Sort createAt field in the descending order
GET /api/posts:get?sort=-createdAt GET /api/posts:get?sort=-createdAt
# Multiple fields sorted jointly, createAt field descending, title A-Z ascending # Sort multiple fields jointly, createAt field descending, title A-Z ascending
GET /api/posts:get?sort=-createdAt,title GET /api/posts:get?sort=-createdAt,title
``` ```
### fields ### fields
Which fields to output Data to output.
```bash ```bash
GET /api/posts:list?fields=name,title GET /api/posts:list?fields=name,title
@ -197,45 +197,45 @@ Response 200 (application/json)
### appends ### appends
Appends a relationship field Fields of additional relationship.
### except ### except
Which fields to exclude (not output) for use in query-related operations. Exclude some fields (not to output), used in actions related to query.
### whitelist ### whitelist
Whitelist Whitelist.
```bash ```bash
POST /api/posts:create?whitelist=title POST /api/posts:create?whitelist=title
{ {
"title": "My first post", "title": "My first post",
"date": "2022-05-19" # The date field will be filtered out and will not be written to the database "date": "2022-05-19" # The date field will be filtered out and not be written to the database
} }
``` ```
### blacklist ### blacklist
Blacklist Blacklist.
```bash ```bash
POST /api/posts:create?blacklist=date POST /api/posts:create?blacklist=date
{ {
"title": "My first post", "title": "My first post",
"date": "2022-05-19" # The date field will be filtered out and will not be written to the database "date": "2022-05-19" # The date field will be filtered out and not be written to the database
} }
``` ```
## Request Response ## Request Response
Format of the response Format of the response is:
```ts ```ts
type ResponseResult = { type ResponseResult = {
data?: any; // Master data data?: any; // Main data
meta?: any; // Additional Data meta?: any; // Additional Data
errors?: ResponseError[]; // Errors errors?: ResponseError[]; // Errors
}; };
@ -248,7 +248,7 @@ type ResponseError = {
### Example ### Example
View list View list:
```bash ```bash
GET /api/posts:list GET /api/posts:list
@ -270,7 +270,7 @@ Response 200 (application/json)
} }
``` ```
View details View details:
```bash ```bash
GET /api/posts:get/1 GET /api/posts:get/1
@ -284,7 +284,7 @@ Response 200 (application/json)
} }
``` ```
Error Error:
```bash ```bash
POST /api/posts:create POST /api/posts:create