Skip to content

index.md

Latest commit

 

History

History
88 lines (68 loc) · 3.08 KB

index.md

File metadata and controls

88 lines (68 loc) · 3.08 KB

API Reference

Welcome to the ObjectQL API Reference. Learn about the unified query protocol that powers multiple API styles including JSON-RPC, REST, GraphQL, and Metadata APIs—all sharing the same validation, permissions, and type safety.

Design Principles

  1. Protocol-First: All APIs accept/return structured JSON, never raw SQL.
  2. Type-Safe: Full TypeScript definitions for all requests/responses.
  3. AI-Friendly: Queries include optional ai_context for explainability, designed for LLM generation.
  4. Secure: Built-in validation, permission checks, SQL injection prevention.
  5. Universal: Same query works across MongoDB, PostgreSQL, SQLite.

Unified ID Field

ObjectQL uses a unified id field as the primary key across all database drivers:

  • Consistent Naming: Always use id in API requests and responses.
  • Database Agnostic: The driver handles mapping (e.g. to _id in Mongo) automatically.
  • String Based: IDs are always strings to ensure JSON compatibility.

API Styles Overview

API Style Use Case Endpoint Pattern Docs
JSON-RPC Universal client, AI agents, microservices POST /api/objectql Read Guide
REST Traditional web apps, mobile apps /api/data/:object Read Guide
GraphQL Modern frontends with complex data requirements POST /api/graphql Read Guide
Metadata Admin interfaces, schema discovery /api/metadata/* Read Guide

🚀 Want to optimize your queries?
Check out the Query Best Practices Guide for performance optimization strategies, detailed comparisons, and recommendations to help you choose the best approach for your use case.

Quick Links

Core Concepts

Advanced Features

Quick Start

Basic Query (JSON-RPC)

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

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

Auto-Generated Specs

For automated tool ingestion, use the following endpoints:

  • OpenAPI / Swagger: /openapi.json (Used by /docs UI)
  • GraphQL Schema: /api/graphql/schema