APIJSON Protocol

Relevant source files

This document provides a comprehensive specification of the APIJSON protocol, which defines the JSON-based request/call and response format for API communication. The protocol enables frontend clients to define their own data structures and query requirements through JSON, eliminating the need for backend developers to write custom API endpoints.

For information about server-side implementation details, see Core ORM Architecture. For access control and validation mechanisms, see Security and Access Control.

Purpose and Scope

The APIJSON Protocol is a JSON transmission specification that:

Defines standardized request/response formats for database operations (CRUD) Document.md9-281
Provides a declarative query language expressed in JSON Document-Chinese.md4-10
Enables flexible data retrieval without requiring backend code changes Document.md158
Supports complex operations including joins, subqueries, aggregations, and remote functions Document.md254-281

This protocol is language-agnostic and can be implemented in any programming language, including Java, Go, C#, PHP, Node.js, Python, and others Document-Chinese.md4-6

Protocol Architecture Overview

The following diagram bridges the "Natural Language Space" of user requests to the "Code Entity Space" by showing how protocol components map to specific interfaces and classes in the APIJSON library.

Request Processing Flow

Title: Protocol to Code Entity Mapping

Sources: Document.md9-12 Document-Chinese.md4-6

HTTP Methods and URL Structure

APIJSON uses a unified endpoint pattern where all operations use HTTP POST (to accommodate complex JSON bodies), but are distinguished by URL path segments that map to specific logic.

Method to Code Mapping

Title: HTTP Method Routing to Protocol Logic

Method Specifications

Method	URL Pattern	Security	Purpose	For details, see
`GET`	`base_url/get/`	Open	General data retrieval Document.md15	HTTP API Endpoints
`HEAD`	`base_url/head/`	Open	Count records and existence check Document-Chinese.md58	HTTP API Endpoints
`GETS`	`base_url/gets/`	Secure	Confidential data retrieval Document-Chinese.md21	HTTP API Endpoints
`POST`	`base_url/post/`	Secure	Insert new records Document.md10	HTTP API Endpoints
`PUT`	`base_url/put/`	Secure	Update existing records Document-Chinese.md21	HTTP API Endpoints
`DELETE`	`base_url/delete/`	Secure	Delete records Document-Chinese.md21	HTTP API Endpoints

Sources: Document.md15-160 Document-Chinese.md21-23

Request Structure and Syntax

All APIJSON requests follow a hierarchical JSON structure. By convention, table names must start with an uppercase letter, while keywords and operators use specific symbols.

Table Objects: Represent a single database table (e.g., "User": {}) Document.md9-12
Array Objects: Represent a collection of records, typically denoted by "[]" or a custom name with a [] suffix (e.g., "User[]": {}) Document.md50-57

For details, see Request Structure and Syntax.

Sources: Document.md46-57 Document-Chinese.md65-75

Functional Operators

APIJSON provides field-level operators as key suffixes to perform advanced SQL-like operations within the JSON request.

Comparison: key{} (IN), key$ (LIKE), key~ (REGEXP) Document-Chinese.md10
Range: key% (BETWEEN), key< (Less than), key> (Greater than).
Reference: key@ (Value reference/join from another object) Document.md103
Subquery: key}{@ (EXISTS) Document.md271

For details, see Functional Operators.

Sources: Document.md97-105 Document.md270-272 Document-Chinese.md10

Array Keywords

Keywords within an array object control pagination, sorting, and the type of result returned.

Pagination: count (LIMIT), page (OFFSET) Document.md51-141
Metadata: query (controls return type of the array) Document-Chinese.md107-108
Relational: join (SQL Join operations) Document.md263

For details, see Array Keywords.

Sources: Document.md140-142 Document-Chinese.md68-73

Object Keywords

Object keywords (prefixed with @) control query behavior at the table level, such as column selection and grouping.

Projection: @column (SELECT fields) Document.md53
Ordering: @order (ORDER BY) Document-Chinese.md58
Aggregation: @group (GROUP BY), @having (HAVING) Document-Chinese.md58
Database Routing: @schema, @database, @role Document-Chinese.md4-6

For details, see Object Keywords.

Sources: Document.md52-54 Document-Chinese.md10

Join Operations

APIJSON supports complex SQL joins using the join keyword combined with operator symbols to define the join type.

Inner Join: &
Left Join: <
Right Join: >
Full Join: |

For details, see Join Operations.

Sources: Document.md262-266 Document-Chinese.md280-283

Remote Functions

Remote functions allow calling server-side logic using the key() syntax. These functions can be implemented via the server's function parser and integrated with script engines like JSR223.

Pre-execution: key-()
Standard execution: key()
Post-execution: key+()

For details, see Remote Functions.

Sources: Document-Chinese.md22

Global Keywords and Parameters

Global parameters affect the entire request context and validation, usually placed at the outermost layer of the JSON request.

Tag: tag (Required for POST/PUT/DELETE to match structure in the Request table) Document-Chinese.md10
Version: version (API version control) Document-Chinese.md10
Format: format (Affects response casing or structure) Document-Chinese.md10

For details, see Global Keywords and Parameters.

Sources: Document-Chinese.md10