nocobase/docs/en-US/api/http/index.md

Overview

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

In NocoBase, resource has two expressions:

• <collection>
• <collection>.<association>

• Collection is the set of all abstract data
• Association is the associated data of collection
• Resource includes both collection and collection.association

Example

• posts Post
• posts.user Post user
• posts.tags Post tags

Action

Action on resource is expressed by :<action>

• <collection>:<action>
• <collection>.<association>:<action>

Built-in global actions for collection or association:

• create
• get
• list
• update
• destroy
• move

Built-in association actions for association only:

• set
• add
• remove
• toggle

Example

• posts:create Create post
• posts.user:get Get post user
• posts.tags:add Add tags to post (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

Locate Resource

• 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 the joint index of collectionIndex and associationIndex must be unique.

When viewing details of association resource, the requested URL needs to provide both <collectionIndex> and <associationIndex>, <collectionIndex> is necessary as <associationIndex> may not be unique.

For example, tables.fields represents the fields of a data table:

GET   /api/tables/table1/fields/title
GET   /api/tables/table2/fields/title

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 can be placed in the headers, parameters (query string), and body (GET requests do not have a body) of the request.

Some special request parameters:

• filter Data filtering, used in actions related to query.
• filterByTk Filter by tk field, used in actions to specify details of data.
• sort Sorting, used in actions related to query.
• fields Date to output, used in actions related to query
• appends Fields of additional relationship, used in actions related to query.
• except Exclude some fields (not to output), used in actions related to query.
• whitelist Fields whitelist, used in actions related to data creation and update.
• blacklist Fields blacklist, used in actions related to data creation and update.

filter

Data filtering.

# simple
GET /api/posts?filter[status]=publish
# json string format is recommended, 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

filterByTk

Filter by tk field. In the default settings:

• 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. To sort in the descending order, put - in front of the field.

# Sort createAt field in the ascending order
GET /api/posts:get?sort=createdAt
# Sort createAt field in the descending order
GET /api/posts:get?sort=-createdAt
# Sort multiple fields jointly, createAt field descending, title A-Z ascending
GET /api/posts:get?sort=-createdAt,title

fields

Data to output.

GET   /api/posts:list?fields=name,title

Response 200 (application/json)
{
  "data": [
    {
      "name": "",
      "title": ""
    }
  ],
  "meta": {}
}

appends

Fields of additional relationship.

except

Exclude some fields (not to output), used in actions related to query.

whitelist

Whitelist.

POST  /api/posts:create?whitelist=title

{
  "title": "My first post",
  "date": "2022-05-19"      # The date field will be filtered out and not be written to the database
}

blacklist

Blacklist.

POST  /api/posts:create?blacklist=date

# The date field will be filtered out and not be written to the database
{
  "title": "My first post"
}

Request Response

Format of the response:

type ResponseResult = {
  data?: any;               // Main 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
  }
}

Error:

POST /api/posts:create

Response 400 (application/json)

{
  errors: [
    {
      message: 'name must be required',
    },
  ],
}