Items API (CRUD Operations)

This documentation is verified against the actual API test suite (test/item.test.js).

Overview

The Items API provides CRUD (Create, Read, Update, Delete) operations for any collection in your database. All endpoints follow the pattern /items/:collection where :collection is your table name.

Key Features:

Dynamic CRUD for any collection
Advanced filtering and querying
Relational data loading
Field selection
Pagination support
Permission-based access control

Get Items

Retrieve items from a collection with optional filtering, sorting, and pagination.

Endpoint: GET /items/:collection

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
collection	string	Name of the collection (table)

Query Parameters

Parameter	Type	Description
fields	array	Fields to return (e.g., `["id", "title"]` or `["*"]` for all)
filter	object	Filter conditions (JSON stringified)
limit	number	Maximum number of items to return
page	number	Page number for pagination

Basic Example

curl "http://localhost:3000/items/posts" \
  -H "Authorization: Bearer YOUR_TOKEN"

With Field Selection

curl "http://localhost:3000/items/posts?fields=%5B%22id%22%2C%22title%22%2C%22content%22%5D" \
  -H "Authorization: Bearer YOUR_TOKEN"

With Pagination

curl "http://localhost:3000/items/posts?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Success (200 OK):

{
  "data": [
    {
      "id": 1,
      "title": "Test Post",
      "content": "This is a test post",
      "published": true,
      "authorId": "user-id"
    }
  ],
  "totalCount": 1
}

Advanced Queries

Relational Queries

Load related data using dot notation in the fields parameter.

Example: Get users with their role information

curl -G "http://localhost:3000/items/baasix_User" \
  --data-urlencode 'fields=["*", "userRoles.role.name"]' \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": [
    {
      "id": "user-id",
      "email": "test@example.com",
      "firstName": "Test",
      "lastName": "User",
      "userRoles": [
        {
          "role": {
            "name": "user"
          }
        }
      ]
    }
  ],
  "totalCount": 1
}

Filtering

Use the filter parameter with JSON-stringified conditions.

Filter Operators:

eq - Equal to
ne - Not equal to
gt - Greater than
gte - Greater than or equal
lt - Less than
lte - Less than or equal
in - In array
nin - Not in array
like - SQL LIKE pattern

Example: Filter users by role name and first name

curl -G "http://localhost:3000/items/baasix_User" \
  --data-urlencode 'filter={"AND":[{"userRoles.role.name":{"eq":"user"}},{"firstName":{"eq":"Test"}}]}' \
  --data-urlencode 'fields=["*", "userRoles.role.name"]' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'page=1' \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter Structure:

{
  "AND": [
    {
      "userRoles.role.name": {
        "eq": "user"
      }
    },
    {
      "firstName": {
        "eq": "Test"
      }
    }
  ]
}

Logical Operators:

AND - All conditions must match
OR - At least one condition must match

Create Item

Create a new item in a collection.

Endpoint: POST /items/:collection

Authentication: Required (Bearer token)

Request Body

Send the item data as JSON. Required fields depend on your schema definition.

{
  "title": "Test Post",
  "content": "This is a test post",
  "published": true,
  "authorId": "user-id"
}

Response

Success (201 Created):

{
  "data": {
    "id": 1,
    "title": "Test Post",
    "content": "This is a test post",
    "published": true,
    "authorId": "user-id",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Error (403 Forbidden):

When user doesn't have create permission:

{
  "error": {
    "message": "You don't have permission to create items in this collection"
  }
}

Example

curl -X POST "http://localhost:3000/items/posts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Post",
    "content": "Post content here",
    "authorId": "user-123"
  }'

Update Item

Update an existing item by ID.

Endpoint: PATCH /items/:collection/:id

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
collection	string	Name of the collection
id	string/number	ID of the item to update

Request Body

Send only the fields you want to update:

{
  "title": "Updated Title",
  "content": "Updated Content",
  "published": true
}

Response

Success (200 OK):

{
  "data": {
    "id": 1
  }
}

Error (403 Forbidden):

When user doesn't have update permission:

{
  "error": {
    "message": "You don't have permission to update items in this collection"
  }
}

Example

curl -X PATCH "http://localhost:3000/items/posts/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Post Title"
  }'

Delete Item

Delete an item by ID.

Endpoint: DELETE /items/:collection/:id

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
collection	string	Name of the collection
id	string/number	ID of the item to delete

Response

Success (200 OK):

{
  "message": "Item deleted successfully"
}

Error (403 Forbidden):

When user doesn't have delete permission:

{
  "error": {
    "message": "You don't have permission to delete items from this collection"
  }
}

Example

curl -X DELETE "http://localhost:3000/items/posts/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Soft Deletes (Paranoid Mode)

If your schema has paranoid: true, items are soft-deleted (marked as deleted but not removed from database). They won't appear in normal queries but can be recovered.

Permissions

All Items API operations require appropriate permissions. Permissions are checked at:

Collection level - Does user have access to this collection?
Action level - Can user perform this action (read/create/update/delete)?
Field level - Can user access/modify these specific fields?

Permission Errors

403 Forbidden:

{
  "error": {
    "message": "You don't have permission to [action] items in this collection"
  }
}

Setting Permissions

Administrators can grant permissions:

curl -X POST "http://localhost:3000/permissions" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_Id": "user-role-id",
    "collection": "posts",
    "action": "read",
    "fields": ["*"]
  }'

Actions:

read - View items
create - Create new items
update - Modify existing items
delete - Remove items

Field Access:

["*"] - All fields
["title", "content"] - Specific fields only

Complete Example Workflow

1. Create a schema

curl -X POST "http://localhost:3000/schemas" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionName": "posts",
    "schema": {
      "name": "Post",
      "fields": {
        "id": { "type": "Integer", "primaryKey": true, "defaultValue": { "type": "AUTOINCREMENT" } },
        "title": { "type": "String", "allowNull": false },
        "content": { "type": "String", "allowNull": false },
        "published": { "type": "Boolean", "default": false },
        "authorId": { "type": "String", "allowNull": false }
      },
      "paranoid": true
    }
  }'

2. Grant permissions

curl -X POST "http://localhost:3000/permissions" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_Id": "user-role-id",
    "collection": "posts",
    "action": "read",
    "fields": ["*"]
  }'

3. Create an item

curl -X POST "http://localhost:3000/items/posts" \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "content": "Hello World",
    "authorId": "user-123",
    "published": true
  }'

4. Query items

curl -G "http://localhost:3000/items/posts" \
  --data-urlencode 'filter={"published":{"eq":true}}' \
  -H "Authorization: Bearer USER_TOKEN"

Core References

Schema Routes - Create and manage collections
Schema Reference Guide - Field types and schema definitions
Database Schema Guide - Relationships and schema patterns

Query System

Item Query Reference Guide - Query parameters and operators
Complete Filter Reference - All filter operators (array, range, geospatial)
Advanced Query Guide - Complex filtering, aggregation, and joins

Access Control

Permission Routes - Configure field-level access control
Authentication Routes - User authentication and sessions
Multi-tenant Guide - Tenant-scoped data isolation

Extensions & Automation

Hooks System - Customize item operations with hooks
Hooks and Endpoints Guide - Hook patterns and service access
Reports Routes - Analytics and aggregation on items

Integration

Integration Guide - Client-side CRUD implementation
Error Handling Guide - Handle item operation errors
API Routes Reference - Complete endpoint listing

On this page