rest.md

REST API

Learn how to use ObjectQL's REST-style API for traditional web and mobile applications. This guide covers RESTful endpoints, resource patterns, and HTTP conventions for accessing ObjectQL data.

Endpoints

Method	Path	Description
GET	/api/data/:object	List records
GET	/api/data/:object/:id	Get single record
POST	/api/data/:object	Create record (or create many if body is an array)
POST	/api/data/:object/bulk-update	Update many records
POST	/api/data/:object/bulk-delete	Delete many records
PUT	/api/data/:object/:id	Update record
DELETE	/api/data/:object/:id	Delete record

List Records

GET /api/data/users?filter={"status":"active"}&sort=created_at&limit=20

Response:

{
  "items": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "size": 20,
    "pages": 8,
    "has_next": true
  }
}

Get Single Record

GET /api/data/users/user_123

Response:

{
  "id": "user_123",
  "name": "Alice",
  "email": "alice@example.com",
  "@type": "users"
}

Create Record

POST /api/data/users
Content-Type: application/json

{
  "name": "Bob",
  "email": "bob@example.com",
  "role": "admin"
}

Response:

{
  "id": "user_456",
  "name": "Bob",
  "email": "bob@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "@type": "users"
}

Update Record

PUT /api/data/users/user_456
Content-Type: application/json

{
  "role": "user"
}

Response:

{
  "id": "user_456",
  "role": "user",
  "updated_at": "2024-01-15T11:00:00Z",
  "@type": "users"
}

Delete Record

DELETE /api/data/users/user_456

Response:

{
  "id": "user_456",
  "deleted": true,
  "@type": "users"
}

Bulk Operations (REST)

Create Many Records

Send an array in the POST body to create multiple records at once.

POST /api/data/users
Content-Type: application/json

[
  {
    "name": "User1",
    "email": "user1@example.com",
    "role": "user"
  },
  {
    "name": "User2",
    "email": "user2@example.com",
    "role": "user"
  },
  {
    "name": "User3",
    "email": "user3@example.com",
    "role": "admin"
  }
]

Response:

{
  "items": [
    {
      "id": "user_101",
      "name": "User1",
      "email": "user1@example.com",
      "role": "user",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_102",
      "name": "User2",
      "email": "user2@example.com",
      "role": "user",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "user_103",
      "name": "User3",
      "email": "user3@example.com",
      "role": "admin",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 3,
  "@type": "users"
}

Update Many Records

Update all records matching the provided filters.

POST /api/data/users/bulk-update
Content-Type: application/json

{
  "filters": {
    "role": "user",
    "status": "inactive"
  },
  "data": {
    "status": "archived",
    "archived_at": "2024-01-15T10:30:00Z"
  }
}

Response:

{
  "count": 15,
  "@type": "users"
}

Delete Many Records

Delete all records matching the provided filters.

POST /api/data/users/bulk-delete
Content-Type: application/json

{
  "filters": {
    "status": "archived",
    "archived_at": ["<", "2023-01-01"]
  }
}

Response:

{
  "count": 42,
  "@type": "users"
}