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

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

• 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

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

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

# 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',
    },
  ],
}