API Reference

Complete API reference for ObjectQL — REST, GraphQL, OData V4, and JSON-RPC protocols

ObjectQL auto-generates APIs from your schema through multiple protocol adapters. All protocols share the same underlying metadata, validation rules, and hook system.

Protocols

REST

Standard CRUD endpoints at /api/data/:object. Best for traditional web and mobile apps.

GraphQL

Full query language at /api/graphql with subscriptions and federation support.

OData V4

Enterprise-grade at /odata/:entity with $filter, $expand, $batch.

JSON-RPC

Universal RPC at POST /api/objectql. Ideal for AI agents and microservices.

Protocol Comparison

Feature	REST	GraphQL	OData V4	JSON-RPC
CRUD operations	✅	✅	✅	✅
Filtering	Query params	Arguments	`$filter`	JSON filters
Field selection	`?fields=`	Native	`$select`	`fields` array
Nested relations	Limited	Native	`$expand`	`expand`
Batch operations	❌	✅	`$batch`	✅
Subscriptions	❌	✅	❌	❌
AI-friendly	Medium	Medium	Low	High
Learning curve	Low	Medium	Medium	Low

Common Concepts

Unified ID Field

All APIs use a consistent id field as the primary key. Database-specific mappings (e.g., MongoDB's _id) are handled automatically by the driver.

Authentication

All protocols support the same authentication methods:

Authorization: Bearer <jwt_token>
X-API-Key: <api_key>

See Authentication for details.

Error Format

All protocols return errors in a consistent format:

{
  "error": {
    "code": "VALIDATION_FAIL",
    "message": "Field 'email' is required",
    "details": { "field": "email", "rule": "required" }
  }
}

See Error Handling for the complete error code reference.

Quick Start

# JSON-RPC — query all active users
curl -X POST http://localhost:3000/api/objectql \
  -H "Content-Type: application/json" \
  -d '{
    "op": "find",
    "object": "users",
    "args": {
      "fields": ["id", "name", "email"],
      "filters": [["is_active", "=", true]],
      "top": 10
    }
  }'