# 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 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 `:` - `:` - `.:` 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 ```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 ``` ## 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 `` and ``, `` is necessary as `` may not be unique. For example, `tables.fields` represents the fields of a data table: ```bash 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. ```bash # 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](http-api/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. ```bash 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. ```bash # 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. ```bash 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. ```bash 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. ```bash POST /api/posts:create?blacklist=date { "title": "My first post", "date": "2022-05-19" # The date field will be filtered out and not be written to the database } ``` ## Request Response Format of the response: ```ts type ResponseResult = { data?: any; // Main 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', }, ], } ```