mirror of
https://github.com/nocobase/nocobase
synced 2024-11-16 13:37:39 +00:00
302 lines
6.4 KiB
Markdown
302 lines
6.4 KiB
Markdown
# 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.
|
|
|
|
## Resource
|
|
|
|
Resource has two expressions in NocoBase.
|
|
|
|
- `<collection>`
|
|
- `<collection>.<association>`
|
|
|
|
<Alert>
|
|
|
|
- collection is the set of all abstract data
|
|
- association is the association data for the collection
|
|
- resource includes both collection and collection.association
|
|
|
|
</Alert>
|
|
|
|
### Example
|
|
|
|
- `posts` Post
|
|
- `posts.user` Post user
|
|
- `posts.tags` Post tags
|
|
|
|
## Action
|
|
|
|
Representing resource operations as `:<action>`
|
|
|
|
- `<collection>:<action>`
|
|
- `<collection>.<association>:<action>`
|
|
|
|
Built-in global operations for collection or association
|
|
|
|
- `create`
|
|
- `get`
|
|
- `list`
|
|
- `update`
|
|
- `destroy`
|
|
- `move`
|
|
|
|
Built-in association operation for association only
|
|
|
|
- `set`
|
|
- `add`
|
|
- `remove`
|
|
- `toggle`
|
|
|
|
### Example
|
|
|
|
- `posts:create` Create posts
|
|
- `posts.user:get` View posts user
|
|
- `posts.tags:add` Attach post tags (associate existing tags with post)
|
|
|
|
## Request URL
|
|
|
|
```bash
|
|
<GET|POST> /api/<collection>:<action>
|
|
<GET|POST> /api/<collection>:<action>/<collectionIndex>
|
|
<GET|POST> /api/<collection>/<collectionIndex>/<association>:<action>
|
|
<GET|POST> /api/<collection>/<collectionIndex>/<association>:<action>/<associationIndex>
|
|
```
|
|
|
|
### Example
|
|
|
|
posts resource
|
|
|
|
```bash
|
|
POST /api/posts:create
|
|
GET /api/posts:list
|
|
GET /api/posts:get/1
|
|
POST /api/posts:update/1
|
|
POST /api/posts:destroy/1
|
|
```
|
|
|
|
posts.comments resource
|
|
|
|
```bash
|
|
POST /api/posts/1/comments:create
|
|
GET /api/posts/1/comments:list
|
|
GET /api/posts/1/comments:get/1
|
|
POST /api/posts/1/comments:update/1
|
|
POST /api/posts/1/comments:destroy/1
|
|
```
|
|
|
|
posts.tags resource
|
|
|
|
```bash
|
|
POST /api/posts/1/tags:create
|
|
GET /api/posts/1/tags:get
|
|
GET /api/posts/1/tags:list
|
|
POST /api/posts/1/tags:update
|
|
POST /api/posts/1/tags:destroy
|
|
POST /api/posts/1/tags:add
|
|
GET /api/posts/1/tags:remove
|
|
```
|
|
|
|
## Resource location
|
|
|
|
- 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
|
|
|
|
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.
|
|
|
|
For example, `tables.fields` indicates the fields of a data table
|
|
|
|
```bash
|
|
GET /api/tables/table1/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
|
|
|
|
## Request parameters
|
|
|
|
Request parameters can be placed in the request's headers, parameters (query string), and body (GET requests do not have a body).
|
|
|
|
A few special request parameters
|
|
|
|
- `filter` Data filtering, used in query-related operations.
|
|
- `filterByTk` filter by tk field, used in operations that specify details of the data.
|
|
- `sort` Sorting, used in query-related operations.
|
|
- `fields` which data to output, for use in query-related operations.
|
|
- `appends` additional relationship fields for use in query-related operations.
|
|
- `except` which fields to exclude (no output), used in query-related operations.
|
|
- `whitelist` fields whitelist, used in data creation and update related operations.
|
|
- `blacklist` fields blacklist, used in data creation and update related operations.
|
|
|
|
### filter
|
|
|
|
Data filter
|
|
|
|
```bash
|
|
# simple
|
|
GET /api/posts?filter[status]=publish
|
|
# Recommend using the json string format, which requires encodeURIComponent encoding
|
|
GET /api/posts?filter={"status":"published"}
|
|
|
|
# filter operators
|
|
GET /api/posts?filter[status.$eq]=publish
|
|
GET /api/posts?filter={"status.$eq":"published"}
|
|
|
|
# $and
|
|
GET /api/posts?filter={"$and": [{"status.$eq":"published"}, {"title.$includes":"a"}]}
|
|
# $or
|
|
GET /api/posts?filter={"$or": [{"status.$eq":"pending"}, {"status.$eq":"draft"}]}
|
|
|
|
# association field
|
|
GET /api/posts?filter[user.email.$includes]=gmail
|
|
GET /api/posts?filter={"user.email.$includes":"gmail"}
|
|
```
|
|
|
|
[Click here for more information about filter operators](http-api/filter-operators)
|
|
|
|
### filterByTk
|
|
|
|
Filter by tk field. By default
|
|
|
|
- collection resource, tk is the primary key of the data table.
|
|
- association resource, tk is the targetKey field of the association.
|
|
|
|
```bash
|
|
GET /api/posts:get?filterByTk=1&fields=name,title&appends=tags
|
|
```
|
|
|
|
### sort
|
|
|
|
Sorting. When sorting in descending order, the fields are preceded by the minus sign `-`.
|
|
|
|
```bash
|
|
# createAt field in ascending order
|
|
GET /api/posts:get?sort=createdAt
|
|
# createAt field descending
|
|
GET /api/posts:get?sort=-createdAt
|
|
# Multiple fields sorted jointly, createAt field descending, title A-Z ascending
|
|
GET /api/posts:get?sort=-createdAt,title
|
|
```
|
|
|
|
### fields
|
|
|
|
Which fields to output
|
|
|
|
```bash
|
|
GET /api/posts:list?fields=name,title
|
|
|
|
Response 200 (application/json)
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "",
|
|
"title": ""
|
|
}
|
|
],
|
|
"meta": {}
|
|
}
|
|
```
|
|
|
|
### appends
|
|
|
|
Appends a relationship field
|
|
|
|
### except
|
|
|
|
Which fields to exclude (not output) for use in query-related operations.
|
|
|
|
### whitelist
|
|
|
|
Whitelist
|
|
|
|
```bash
|
|
POST /api/posts:create?whitelist=title
|
|
|
|
{
|
|
"title": "My first post",
|
|
"date": "2022-05-19" # The date field will be filtered out and will not be written to the database
|
|
}
|
|
```
|
|
|
|
### blacklist
|
|
|
|
Blacklist
|
|
|
|
```bash
|
|
POST /api/posts:create?blacklist=date
|
|
|
|
{
|
|
"title": "My first post",
|
|
"date": "2022-05-19" # The date field will be filtered out and will not be written to the database
|
|
}
|
|
```
|
|
|
|
## Request Response
|
|
|
|
Format of the response
|
|
|
|
```ts
|
|
type ResponseResult = {
|
|
data?: any; // Master data
|
|
meta?: any; // Additional Data
|
|
errors?: ResponseError[]; // Errors
|
|
};
|
|
|
|
type ResponseError = {
|
|
code?: string;
|
|
message: string;
|
|
};
|
|
```
|
|
|
|
### Example
|
|
|
|
View list
|
|
|
|
```bash
|
|
GET /api/posts:list
|
|
|
|
Response 200 (application/json)
|
|
|
|
{
|
|
data: [
|
|
{
|
|
id: 1
|
|
}
|
|
],
|
|
meta: {
|
|
count: 1
|
|
page: 1,
|
|
pageSize: 1,
|
|
totalPage: 1
|
|
},
|
|
}
|
|
```
|
|
|
|
View details
|
|
|
|
```bash
|
|
GET /api/posts:get/1
|
|
|
|
Response 200 (application/json)
|
|
|
|
{
|
|
data: {
|
|
id: 1
|
|
}
|
|
}
|
|
```
|
|
|
|
Error
|
|
|
|
```bash
|
|
POST /api/posts:create
|
|
|
|
Response 400 (application/json)
|
|
|
|
{
|
|
errors: [
|
|
{
|
|
message: 'name must be required',
|
|
},
|
|
],
|
|
}
|
|
```
|