* feat: nocobase build * chore: update build scripts * chore: update build scripts * chore(versions): 😊 publish v0.7.0-alpha.33 * chore: independent version * chore: nocobase build * chore(versions): 😊 publish v0.7.0-alpha.34 * feat: nocobase-cli * feat: nocobase-cli * chore: update dependencies * feat: improve code * refactor: create-nocobase-app * chore(versions): 😊 publish v0.7.0-alpha.35 * feat: @nocobase/devtools * chore(versions): 😊 publish v0.7.0-alpha.36 * chore: update dependencies * chore(versions): 😊 publish v0.7.0-alpha.37 * feat: improve code * chore(versions): 😊 publish v0.7.0-alpha.38 * feat: improve code * chore(versions): 😊 publish v0.7.0-alpha.39 * feat: update deps * chore(versions): 😊 publish v0.7.0-alpha.40 * chore: update devDependencies * chore(versions): 😊 publish v0.7.0-alpha.41 * fix: postinstall * chore(versions): 😊 publish v0.7.0-alpha.42 * chore: improve code * chore(versions): 😊 publish v0.7.0-alpha.43 * chore: execa * chore(versions): 😊 publish v0.7.0-alpha.44 * chore(cli): allow unknown option * chore(versions): 😊 publish v0.7.0-alpha.45 * fix: default envs * chore(versions): 😊 publish v0.7.0-alpha.45 * fix: package argument for build command * chore(versions): 😊 publish v0.7.0-alpha.46 * fix: improve code * chore(versions): 😊 publish v0.7.0-alpha.48 * feat: clean & doc * chore(versions): 😊 publish v0.7.0-alpha.49 * feat: compilation tips * feat: upgrade command * chore(versions): 😊 publish v0.7.0-alpha.50 * fix: unexpected token ] in JSON * chore(versions): 😊 publish v0.7.0-alpha.51 * fix: upgrade command * chore(versions): 😊 publish v0.7.0-alpha.52 * fix: remove export action from available action * fix: db sync after upgrade * chore(versions): 😊 publish v0.7.0-alpha.53 * feat: upgrade log * chore(versions): 😊 publish v0.7.0-alpha.54 * docs: updates * feat: updates * docs(cli): update usage description * feat: updates * docs: updates * docs: updates * docs: toc * feat: sdk * docs: updates * docs: updates * docs: updates * Update index.md * docs: updates * Update release-notes.md * Update roadmap.md * Update index.md * Update contributing.md * Update contributing.md * Update index.md * Update index.md * Update nocobase-cli.md * Update nocobase-cli.md * fix: user plugin initialization data * Update env.md * Update env.md * Update directory-structure.md * Update index.md * Update action-api.md * Update filter-operators.md * docs: update thanks.md * Update index.md * Update javascript-sdk.md * Update rest-api.md * Update installation.md * Update installation.md * Update upgrading.md * Update upgrading.md * Update upgrading.md * Update installation.md * Update installation.md * Create release-notes.md * Update release-notes.md * feat: updates * feat: update docs * feat: update release-notes.md * feat: switch language * feat: updates * Add files via upload * Add files via upload * Update important-features.md * Update thanks.md * feat: nocobase postinstall * Update index.md * Create why-different.md * Update why-different.md * Create who-is-for.md * Rename who-is-for.md to who.md * feat: update docs * Rename why-different.md to why.md * Update why.md * Update menus.ts * Update why-nocobase.md * Create who.md * Create why.md * feat: updates * chore(versions): 😊 publish v0.7.0-alpha.55 * feat: tips * Update who.md * Update who.md * feat: update docs * feat: update doc menus * fix: plugin client dist * docs: update contributing.md * docs: update readme.md * docs: update readme.md * docs: update readme.md * Update functional-zoning.md * fix: br Co-authored-by: Zhou <zhou.working@gmail.com>
6.4 KiB
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>
- collection is the set of all abstract data
- association is the association data for the collection
- resource includes both collection and collection.association
Example
postsPostposts.userPost userposts.tagsPost tags
Action
Representing resource operations as :<action>
<collection>:<action><collection>.<association>:<action>
Built-in global operations for collection or association
creategetlistupdatedestroymove
Built-in association operation for association only
setaddremovetoggle
Example
posts:createCreate postsposts.user:getView posts userposts.tags:addAttach post tags (associate existing tags with post)
Request URL
<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
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
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
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,collectionIndexmust be unique - association resource, locates the data to be processed by
collectionIndexandassociationIndexjointly,associationIndexmay not be unique, butcollectionIndexandassociationIndex'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
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
filterData filtering, used in query-related operations.filterByTkfilter by tk field, used in operations that specify details of the data.sortSorting, used in query-related operations.fieldswhich data to output, for use in query-related operations.appendsadditional relationship fields for use in query-related operations.exceptwhich fields to exclude (no output), used in query-related operations.whitelistfields whitelist, used in data creation and update related operations.blacklistfields blacklist, used in data creation and update related operations.
filter
Data filter
# 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 infomation about 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.
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 -.
# 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
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
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
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
type ResponseResult = {
data?: any; // Master data
meta?: any; // Additional Data
errors?: ResponseError[]; // Errors
};
type ResponseError = {
code?: string;
message: string;
};
Example
View list
GET /api/posts:list
Response 200 (application/json)
{
data: [
{
id: 1
}
],
meta: {
count: 1
page: 1,
pageSize: 1,
totalPage: 1
},
}
View details
GET /api/posts:get/1
Response 200 (application/json)
{
data: {
id: 1
},
meta: {
count: 1
page: 1,
pageSize: 1,
totalPage: 1
},
}
Error
POST /api/posts:create
Response 400 (application/json)
{
errors: [
{
message: 'name must be required',
},
],
}