Add comprehensive API documentation for metadata-driven interface planning

[Copilot]

Addresses request for English documentation on planning API interfaces for ObjectQL's extensive metadata capabilities.

Changes

New Documentation Files (~47KB total)

• docs/api/README.md (22KB) - Complete API reference

  • JSON-RPC protocol (primary): universal operations (find, findOne, create, update, delete, count, action)
  • REST endpoints: traditional CRUD interface
  • Metadata API: runtime schema introspection and discovery
  • WebSocket API: planned real-time features
  • Advanced querying: complex filters, joins, aggregations, pagination
  • OpenAPI/Swagger auto-generation
  • Error handling and rate limiting patterns

• docs/api/authentication.md (14KB) - Security implementation

  • Authentication strategies: JWT (recommended), API keys, sessions, OAuth2/OIDC
  • Multi-level authorization: object → operation → field → record
  • Dynamic permissions with special variables ($current_user, $today)
  • Password hashing with bcrypt/argon2
  • Multi-tenancy isolation patterns

• docs/api/quick-reference.md (7KB) - Developer cheat sheet

  • All operations condensed
  • Complete operator reference table
  • Common query patterns

• docs/api/index.md (4KB) - Documentation hub

Updated Files

• README.md - Added API reference section
• docs/guide/index.md - Added API access section

Example: Planning API Interfaces

// JSON-RPC: Universal protocol for all clients, AI agents
POST /api/objectql
{
  "op": "find",
  "object": "orders",
  "args": {
    "fields": ["order_no", "amount"],
    "filters": [["status", "=", "paid"], "and", ["amount", ">", 1000]],
    "expand": { "customer": { "fields": ["name", "email"] } }
  }
}

// REST: Traditional web/mobile endpoints
GET /api/data/orders?filter={"status":"paid"}&limit=20

// Metadata: Runtime schema introspection
GET /api/metadata/objects/orders
{
  "name": "orders",
  "fields": [...],
  "actions": [...],
  "permissions": [...]
}

Enables developers to choose appropriate API style based on use case while leveraging ObjectQL's metadata for auto-generated specs, dynamic permissions, and AI-friendly query context.

Original prompt

让我拥有这么多元数据功能的时候，我该如何规划Api接口？请先给我更新英文文档

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds comprehensive English API documentation (~47KB total) for ObjectQL's metadata-driven interface planning capabilities. The documentation addresses how developers should plan and use API interfaces when working with ObjectQL's extensive metadata features.

Changes:

• Added four new API documentation files covering JSON-RPC, REST, Metadata APIs, authentication strategies, and quick reference guides
• Updated README.md and docs/guide/index.md to include links to the new API documentation section
• Provided detailed examples of API operations, authentication patterns, permission systems, and best practices

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/api/README.md	Comprehensive 22KB API reference covering JSON-RPC, REST, Metadata, and WebSocket APIs with detailed operation examples and error handling
docs/api/authentication.md	14KB security implementation guide covering JWT, API keys, sessions, OAuth2, multi-level authorization, and security best practices
docs/api/quick-reference.md	7KB developer cheat sheet with condensed operation examples, filter operators, and common query patterns
docs/api/index.md	4KB documentation hub providing quick links and getting started examples for different API styles
README.md	Added API Reference section with quick example demonstrating JSON-RPC usage
docs/guide/index.md	Added API Access section linking to the new comprehensive API documentation