# 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 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 `:` - `:` - `.:` 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 /api/: /api/:/ /api///: /api///:/ ``` ### 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 `` and ``, `` is not redundant because `` 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 infomation 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', }, ], } ```