CRUD Endpoints

Quickback automatically generates RESTful CRUD endpoints for each resource you define. This page covers how to use these endpoints.

Endpoint Overview

For a resource named rooms, Quickback generates:

Method	Endpoint	Description
GET	/rooms	List all records
GET	/rooms/:id	Get a single record
POST	/rooms	Create a new record
PATCH	/rooms/:id	Update a record
DELETE	/rooms/:id	Delete a record
PUT	/rooms/:id	Upsert a record (requires config)

List Records

GET /rooms

Returns a paginated list of records the user has access to.

Query Parameters

Parameter	Description	Example
limit	Number of records to return (default: 50, max: 100)	?limit=25
offset	Number of records to skip	?offset=50
sort	Field to sort by	?sort=createdAt
order	Sort direction: asc or desc	?order=desc

Filtering

Filter records using query parameters:

GET /rooms?status=active                    # Exact match
GET /rooms?capacity.gt=10                   # Greater than
GET /rooms?capacity.gte=10                  # Greater than or equal
GET /rooms?capacity.lt=50                   # Less than
GET /rooms?capacity.lte=50                  # Less than or equal
GET /rooms?status.ne=deleted                # Not equal
GET /rooms?name.like=Conference             # Pattern match (LIKE %value%)
GET /rooms?status.in=active,pending,review  # IN clause

Response

{
  "data": [
    {
      "id": "room_123",
      "name": "Conference Room A",
      "capacity": 10,
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

Get Single Record

GET /rooms/:id

Returns a single record by ID.

Response

{
  "data": {
    "id": "room_123",
    "name": "Conference Room A",
    "capacity": 10,
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Errors

Status	Description
404	Record not found or not accessible
403	User lacks permission to view this record

Create Record

POST /rooms
Content-Type: application/json

{
  "name": "Conference Room B",
  "capacity": 8,
  "roomType": "meeting"
}

Creates a new record. Only fields listed in guards.createable are accepted.

Response

{
  "data": {
    "id": "room_456",
    "name": "Conference Room B",
    "capacity": 8,
    "roomType": "meeting",
    "createdAt": "2024-01-15T11:00:00Z",
    "createdBy": "user_789"
  }
}

Errors

Status	Description
400	Invalid field or missing required field
403	User lacks permission to create records

Update Record

PATCH /rooms/:id
Content-Type: application/json

{
  "name": "Updated Room Name",
  "capacity": 12
}

Updates an existing record. Only fields listed in guards.updatable are accepted.

Response

{
  "data": {
    "id": "room_123",
    "name": "Updated Room Name",
    "capacity": 12,
    "modifiedAt": "2024-01-15T12:00:00Z",
    "modifiedBy": "user_789"
  }
}

Errors

Status	Description
400	Invalid field or field not updatable
403	User lacks permission to update this record
404	Record not found

Delete Record

DELETE /rooms/:id

Deletes a record. Behavior depends on the delete.mode configuration.

Soft Delete (default)

Sets deletedAt and deletedBy fields. Record remains in database but is filtered from queries.

Hard Delete

Permanently removes the record from the database.

Response

{
  "data": {
    "id": "room_123",
    "deleted": true
  }
}

Errors

Status	Description
403	User lacks permission to delete this record
404	Record not found

Upsert Record (PUT)

PUT /rooms/:id
Content-Type: application/json

{
  "name": "External Room",
  "capacity": 20,
  "externalId": "ext-123"
}

Creates or updates a record by ID. Requires special configuration:

1. generateId: false in database config
2. guards: false in resource definition

Behavior

• If record exists: Updates all provided fields
• If record doesn't exist: Creates with the provided ID

Use Cases

• Syncing data from external systems
• Webhook handlers with external IDs
• Idempotent operations (safe to retry)

See Guards documentation for setup details.

Authentication

All endpoints require authentication. Include your auth token in the request header:

Authorization: Bearer <your-token>

The user's context (userId, roles, organizationId) is extracted from the token and used to:

1. Apply firewall filters (data isolation)
2. Check access permissions
3. Set audit fields (createdBy, modifiedBy)

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Common Error Codes

Code	Status	Description
BAD_REQUEST	400	Invalid request data
UNAUTHORIZED	401	Missing or invalid auth token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Record not found
VALIDATION_ERROR	400	Field validation failed