API Documentation

Welcome to the ObjectQL API Reference.

Quick Links

Main Documentation

• Complete API Reference - Comprehensive guide to all API endpoints and features

Authentication & Security

• Authentication Guide - JWT, API keys, OAuth2, and more
• Rate Limiting
• Error Handling

API Styles

ObjectQL supports multiple API styles to fit your use case:

1. JSON-RPC API (Primary)

• Endpoint: POST /api/objectql
• Use Case: Universal client, AI agents, microservices
• Documentation

Operations:

• find - Query multiple records
• findOne - Get single record
• create - Insert new record
• update - Modify existing record
• delete - Remove record
• count - Count records
• action - Execute custom server-side operation

2. REST API

• Endpoints: GET/POST/PUT/DELETE /api/data/:object
• Use Case: Traditional web apps, mobile apps
• Documentation

3. Metadata API

• Endpoints: GET /api/metadata/*
• Use Case: Admin interfaces, schema discovery, runtime introspection
• Documentation

Endpoints:

• GET /api/metadata/objects - List all objects
• GET /api/metadata/objects/:name - Get object schema
• GET /api/metadata/objects/:name/fields/:field - Get field metadata
• GET /api/metadata/objects/:name/actions - List custom actions

4. WebSocket API (Planned)

• Endpoint: ws://host/api/realtime
• Use Case: Real-time apps, live updates
• Documentation

Additional Resources

• OpenAPI/Swagger Spec - Auto-generated API specification
• Best Practices - Optimization tips
• Examples - Complete code examples

Quick Start

Basic Query Example

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
    }
  }'

Create Record Example

curl -X POST http://localhost:3000/api/objectql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "op": "create",
    "object": "tasks",
    "args": {
      "name": "Complete documentation",
      "priority": "high",
      "due_date": "2024-01-20"
    }
  }'

Get Metadata Example

curl http://localhost:3000/api/metadata/objects/users

Response Format

All APIs return consistent JSON responses:

Success:

{
  "data": {
    // Your data here
  }
}

Error:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Related Documentation

• Query Language Specification - Deep dive into filter syntax
• Actions Guide - Building custom operations
• Hooks Guide - Event-driven logic
• Server Integration - Deploying ObjectQL
• Permissions - Access control

Support

• Issues: GitHub Issues
• Documentation: Main Docs
• Examples: Examples Directory

---

Last Updated: January 2024
API Version: 1.0.0