APIJSON is a JSON-based network transmission protocol and an ORM (Object-Relational Mapping) library that enables coding-free API development. It allows frontend clients to define the structure and content of API responses through JSON request syntax, eliminating the need for backend developers to write individual API endpoints for most data operations.
Scope: This page provides a high-level introduction to APIJSON's architecture, core components, and design principles. For detailed protocol specifications, see APIJSON Protocol. For implementation details, see Core ORM Architecture. For security mechanisms, see Security and Access Control.
APIJSON consists of two primary layers:
The protocol enables clients to specify exactly what data they need and how it should be structured, while the ORM layer handles security validation, SQL generation, query execution, and response formatting automatically.
Sources: README.md99-101 README.md10
The following diagram illustrates the complete APIJSON architecture, mapping from client applications through the protocol and implementation layers to the database. Node names correspond to actual code entities (classes, methods, tables) that can be searched in the codebase:
Key architectural characteristics:
AbstractParser.parse() method handles all requests without requiring custom endpoint implementations for standard CRUD operationsAbstractVerifier enforces authentication, authorization, and validation before any database accessAbstractSQLConfig generates dialect-specific SQL for 30+ database typesSources: README.md58-74 README.md99-115 Diagram 1 from system overview, APIJSONORM package structure references
The diagram below maps the complete request lifecycle to actual methods in the APIJSONORM codebase. Each node corresponds to a specific method or configuration that can be located in the source code:
Key methods in the flow:
| Class | Method | File Location | Purpose |
|---|---|---|---|
| AbstractParser | parse(String json) | apijson/orm/AbstractParser.java | Entry point for all requests |
| AbstractVerifier | verifyLogin() | apijson/orm/AbstractVerifier.java | Authenticate user session |
| AbstractVerifier | verifyAccess(SQLConfig) | apijson/orm/AbstractVerifier.java | Check Access table for RBAC |
| AbstractObjectParser | parseObject(JSONObject) | apijson/orm/AbstractObjectParser.java | Recursive JSON parsing |
| AbstractSQLConfig | gainSQL() | apijson/orm/AbstractSQLConfig.java | Generate SQL from SQLConfig |
| AbstractSQLExecutor | execute(SQLConfig) | apijson/orm/AbstractSQLExecutor.java | Execute SQL query |
Sources: Document.md289-336 Diagram 2 from system overview, APIJSONORM/src/main/java/apijson/orm/ class references
The APIJSONORM implementation consists of six abstract classes that form the processing pipeline. All classes are located in the apijson.orm package:
| Component | Class Name | File Path | Primary Methods | Responsibility |
|---|---|---|---|---|
| Entry Point | AbstractParser | APIJSONORM/src/main/java/apijson/orm/AbstractParser.java | parse(String json, RequestMethod method)parseResponse(JSONObject response)onComplete() | Request orchestration, transaction management, global configuration extraction |
| Security | AbstractVerifier | APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java | verifyLogin()verifyRequest()verifyContent(JSONObject content)verifyAccess(SQLConfig config) | Authentication, structure validation via Request table, RBAC via Access table |
| JSON Parsing | AbstractObjectParser | APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java | parseObject(JSONObject request)parseArray(JSONObject array)onTableParse(String table)onFunctionParse(String key) | Recursive JSON structure parsing, keyword interpretation, nested object/array handling |
| SQL Generation | AbstractSQLConfig | APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java | gainSQL()getSQL(boolean prepared)getJoin()setMethod(RequestMethod method)getSQLDatabase() | Database-agnostic SQL generation, dialect-specific syntax handling, multi-database type detection |
| Execution | AbstractSQLExecutor | APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java | execute(SQLConfig config)executeQuery(SQLConfig config)executeUpdate(SQLConfig config)getConnection(SQLConfig config) | Query execution, connection management, result caching via cacheMap |
| Functions | AbstractFunctionParser | APIJSONORM/src/main/java/apijson/orm/AbstractFunctionParser.java | invoke(Function function, Object... args)execute(String script) | Remote function calls, script execution (JavaScript/Python/Java) |
These components are abstract classes that must be extended to create a concrete implementation. The reference implementation is in APIJSONDemo which extends these classes in the apijson.demo package. For detailed information about each component, see Component Overview.
Sources: README.md99-115 Diagram 1 from system overview, APIJSONORM package structure
APIJSON uses a hierarchical JSON structure with three levels of control:
| Method | Endpoint | Access Level | Purpose |
|---|---|---|---|
| GET | /get/ | Public | Read data without authentication |
| HEAD | /head/ | Public | Count records without authentication |
| GETS | /gets/ | Requires tag | Read data with authentication |
| HEADS | /heads/ | Requires tag | Count records with authentication |
| POST | /post/ | Requires tag | Create new records |
| PUT | /put/ | Requires tag | Update existing records |
| DELETE | /delete/ | Requires tag | Delete records |
@database, @role, tag, version) configure the entire requestUser, Moment) represent database tables[]) retrieves multiple records with pagination@column, @order, @group) control SQL generation@, {}, $, ~, <>) enable advanced queriesFor complete protocol specification, see APIJSON Protocol.
Sources: Document.md289-302 Document.md314-336
APIJSON's AbstractSQLConfig class provides dialect-aware SQL generation for 30+ database systems through the getSQLDatabase() method and database-specific logic:
| Category | Examples | JDBC Support | Configuration |
|---|---|---|---|
| Relational | MySQL 5.7+, PostgreSQL 9.5+, Oracle 12C+, SQL Server 2012+, DB2 7.1+, MariaDB 10.0+, TiDB 2.1+ | Full | @database:"MYSQL" / @database:"POSTGRESQL" |
| Analytical | ClickHouse 21.1+, Presto 0.277+, Trino 400+, Hive 3.1+, Snowflake 7.0+, Databricks 13.0+ | Full | @database:"CLICKHOUSE" / @database:"PRESTO" |
| NoSQL | MongoDB Atlas+, Redis 5.0+, Elasticsearch 7.17+, Milvus 2.2.0+ | Limited | Custom driver/adapter required |
| Time-Series | InfluxDB 2.6+, TDengine 2.6+, TimescaleDB 17.1+, IoTDB 1.3+ | Full | @database:"TDENGINE" / @database:"POSTGRESQL" |
| Chinese DBs | Dameng 7.6+, Kingbase 8.6+, openGauss 5.0+, TDSQL cloud | Full | @database:"DAMENG" / @database:"KINGBASE" |
The AbstractSQLConfig class adapts SQL generation based on the detected database type:
Quote Character Selection:
`tableName`"tableName"[tableName]Pagination Syntax:
LIMIT 10 OFFSET 20OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLYWHERE ROWNUM <= 30 AND ROWNUM > 20JSON Functions:
JSON_CONTAINS(column, value)column @> value::jsonbISJSON(column) AND value IN (SELECT value FROM OPENJSON(column))For database configuration details and connection setup, see Database Support. For the complete list of supported databases, see README.md21-56
Sources: README.md21-56 Diagram 3 from system overview, APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java references
APIJSON has implementations across multiple programming languages:
| Language | Repository | Maintainer Type | Status |
|---|---|---|---|
| Java | APIJSON-Demo/APIJSON-Java-Server | Official (Tencent) | Reference implementation |
| Go | glennliao/apijson-go, j2go/apijson-go | Community | Active |
| C# | liaozb/APIJSON.NET | Community | Active |
| PHP | kvnZero/hyperf-APIJSON | Community | Active |
| Node.js | kevinaskin/apijson-node | Community | Active |
| Python | zhangchunlin/uliweb-apijson | Community | Active |
| Rust | panda-base | Community | Experimental |
For integration examples, see Backend Setup and Frontend Integration.
Sources: README.md58-79 CONTRIBUTING.md1-78
APIJSON includes companion tools for testing and documentation:
HTTP API testing tool with machine learning capabilities:
Unit testing automation:
Both tools integrate with APIJSON servers and can be used standalone. See Ecosystem and Tools for details.
Sources: README.md151-187 Diagram 1 from system overview
APIJSON follows three core principles that eliminate the need for traditional backend API development:
Instead of writing endpoint handlers in controllers and services, developers configure three database tables that drive the entire system:
Access Table Structure:
CREATE TABLE Access (
id BIGINT PRIMARY KEY,
name VARCHAR(50), -- Table name
alias VARCHAR(20), -- Table alias
get TINYINT, -- READ permission (0-5)
head TINYINT, -- COUNT permission (0-5)
gets TINYINT, -- Secure READ permission (0-5)
heads TINYINT, -- Secure COUNT permission (0-5)
post TINYINT, -- CREATE permission (0-5)
put TINYINT, -- UPDATE permission (0-5)
delete TINYINT -- DELETE permission (0-5)
);
Request Table Structure:
CREATE TABLE Request (
id BIGINT PRIMARY KEY,
method VARCHAR(10), -- GET, HEAD, POST, PUT, DELETE
tag VARCHAR(20), -- Unique identifier for this request structure
version INT, -- API version number
structure TEXT, -- Required JSON structure (with MUST, REFUSE, UNIQUE rules)
detail TEXT -- Additional validation rules
);
Function Table Structure:
CREATE TABLE Function (
id BIGINT PRIMARY KEY,
name VARCHAR(50), -- Function name (callable as key())
arguments TEXT, -- Comma-separated argument list
demo TEXT, -- Example usage
detail TEXT -- Implementation details/script
);
These tables are queried by AbstractVerifier methods:
verifyAccess() queries Access table: SELECT * FROM Access WHERE name=? AND role=?verifyRequest() queries Request table: SELECT * FROM Request WHERE method=? AND tag=?AbstractFunctionParser.invoke() queries Function table: SELECT * FROM Function WHERE name=?The JSON protocol gives clients complete control over response structure through keywords parsed by AbstractObjectParser:
Field Selection via @column:
Pagination via count and page:
Joins via @ reference operator:
Aggregation via @group and @having:
Every request passes through a five-layer security pipeline implemented in AbstractVerifier and related classes:
Rate Limiting Methods:
getMaxQueryCount(): Maximum number of queries per request (default: 50)getMaxUpdateCount(): Maximum number of updates per transaction (default: 10)getMaxQueryDepth(): Maximum nested query depth (default: 3)getMaxObjectCount(): Maximum objects in one request (default: 100)getMaxSQLCount(): Maximum SQL statements per request (default: 20)For complete security implementation, see Security and Access Control.
Sources: README.md103-115 Diagram 4 from system overview, APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java references
To begin using APIJSON:
Backend developers: Set up the APIJSON server and configure the Access/Request/Function tables. See Backend Setup.
Frontend developers: Learn the JSON request syntax and make HTTP calls. See Frontend Integration and Your First API Request.
Testing: Use APIAuto to test requests and generate documentation. See Ecosystem and Tools.
For architectural deep dives, start with System Architecture or Core ORM Architecture.
Sources: README.md191-208 Document.md1-284
APIJSON is open source under the Apache License 2.0, permitting commercial and non-commercial use without restrictions.
Community stats:
For contributing guidelines, see Contributing.
Sources: README.md1-3 README.md401-406 CONTRIBUTING.md1-89 LICENSE1-11
Refresh this wiki