If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tencent/APIJSON shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3d ago
• 8 active contributors
• Other licensed
• Tests present
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tencent/APIJSON repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/APIJSON.

What it runs against: a local clone of Tencent/APIJSON — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tencent/APIJSON | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/APIJSON. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/APIJSON.git
#   cd APIJSON
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tencent/APIJSON and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tencent/APIJSON(\\.git)?\\b" \\
  && ok "origin remote is Tencent/APIJSON" \\
  || miss "origin remote is not Tencent/APIJSON (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "APIJSONORM/src/main/java/apijson/orm/AbstractParser.java" \\
  && ok "APIJSONORM/src/main/java/apijson/orm/AbstractParser.java" \\
  || miss "missing critical file: APIJSONORM/src/main/java/apijson/orm/AbstractParser.java"
test -f "APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java" \\
  && ok "APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java" \\
  || miss "missing critical file: APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java"
test -f "APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java" \\
  && ok "APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java" \\
  || miss "missing critical file: APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java"
test -f "APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java" \\
  && ok "APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java" \\
  || miss "missing critical file: APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java"
test -f "APIJSONORM/src/main/java/apijson/orm/ObjectParser.java" \\
  && ok "APIJSONORM/src/main/java/apijson/orm/ObjectParser.java" \\
  || miss "missing critical file: APIJSONORM/src/main/java/apijson/orm/ObjectParser.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tencent/APIJSON"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

APIJSON is a zero-code ORM library that auto-generates REST APIs and documentation from database schemas without backend coding, allowing frontend clients to customize response JSON structure and fields in real-time. It supports 10+ databases (MySQL, PostgreSQL, Oracle, SQLServer, DB2, TiDB, DuckDB, etc.) and uses a declarative JSON request format to define queries, filters, joins, and pagination without writing SQL. Monolithic single-module Maven structure: APIJSONORM/src/main/java/apijson contains the core framework split into two layers—top-level utilities (JSON.java, JSONRequest.java, JSONResponse.java, SQL.java, StringUtil.java) and apijson/orm/ subdirectory with the ORM engine (AbstractParser.java, AbstractSQLConfig.java, AbstractSQLExecutor.java, ObjectParser.java, SQLExecutor.java). The orm package follows an Abstract Base + Concrete Implementation pattern (AbstractXxx paired with Xxx classes).

Full-stack developers and product teams who want to eliminate backend boilerplate—specifically: frontend engineers who need flexible API contracts without waiting for backend API changes, backend engineers building rapid-prototyping systems, and enterprises standardizing on schema-driven API generation across microservices.

Production-ready. The project is maintained by Tencent, versioned at 8.1.6 (mature semver), and built for enterprise use across multiple database systems. The pom.xml shows stable dependency management (Java 1.8+), but the file listing shows no explicit test directory structure visible, which is a minor gap. Active development is evident from the comprehensive database support matrix.

Low risk for core functionality but monitor for breaking changes in minor versions given the broad database compatibility surface. The pom.xml has zero explicit dependencies (clean dependency tree), reducing supply-chain risk. However, the lack of visible test files in the top 60 structure and no GitHub Actions CI configuration shown suggests testing coverage may not be transparent. Single maintainer (Tencent) means updates depend on their roadmap.

Visible focus on database compatibility expansion (supporting DuckDB, Milvus vector DB, Dameng, Kingbase, openGauss) and likely parser/executor robustness. The presence of AbstractFunctionParser.java and FunctionParser.java suggests active work on SQL function support. No specific PR/milestone data in file listing, but the version 8.1.6 and comprehensive DB support matrix indicate ongoing stability releases.

Clone the repository, then build with Maven:

git clone https://github.com/Tencent/APIJSON.git
cd APIJSON/APIJSONORM
mvn clean install
mvn package

The JAR will be available in target/. No external services required to build—it's a pure library.

Daily commands: This is a library, not an executable service. To use in your project, depend on the built JAR. For development:

cd APIJSONORM
mvn compile          # Compile source
mvn test             # Run tests (if available)
mvn javadoc:javadoc # Generate docs

To integrate: add to pom.xml as a dependency or shade/include the compiled JAR in your backend application.

• APIJSONORM/src/main/java/apijson/orm/AbstractParser.java — Core abstract parser that orchestrates request parsing, SQL generation, and response building—every ORM flow starts here.
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java — Defines SQL configuration and query building logic; critical for understanding how APIJSON translates requests into SQL.
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java — Executes generated SQL and handles database interactions; the bridge between query planning and actual data retrieval.
• APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java — Validates request permissions and access control; essential for understanding security enforcement in APIJSON.
• APIJSONORM/src/main/java/apijson/orm/ObjectParser.java — Implements JSON object parsing strategy; handles transformation of client JSON requests into structured database queries.
• APIJSONORM/src/main/java/apijson/JSONRequest.java — Core request model parsing JSON into structured request objects; foundational for all request handling.
• APIJSONORM/pom.xml — Maven configuration defining dependencies and build configuration; necessary for setting up development environment.

Add Support for a New Database Type or SQL Dialect

1. Create a new concrete implementation of AbstractSQLConfig that overrides dialect-specific methods like getTableQuote(), getColumnQuote(), and getPageSql(). (APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java)
2. Create a corresponding SQLCreator factory that instantiates your new SQL config implementation based on database type detection. (APIJSONORM/src/main/java/apijson/orm/SQLCreator.java)
3. Implement AbstractSQLExecutor or override getConnection() to handle database-specific connection logic and type conversions. (APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java)
4. Register your new database dialect in the ParserCreator by adding a case to detect your database type and instantiate the appropriate parser chain. (APIJSONORM/src/main/java/apijson/orm/ParserCreator.java)

Add Custom Security or Access Control Rules

1. Extend AbstractVerifier and override verify() method to implement your custom permission checking logic before query execution. (APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java)
2. Define additional access control models or extend the existing Access model to represent your authorization schemes. (APIJSONORM/src/main/java/apijson/orm/model/Access.java)
3. Register your custom verifier via VerifierCreator to ensure it's instantiated for every request. (APIJSONORM/src/main/java/apijson/orm/VerifierCreator.java)
4. Add custom exceptions in the exception package to represent your domain-specific authorization failures. (APIJSONORM/src/main/java/apijson/orm/exception/CommonException.java)

Add Support for Custom Query Functions or Expressions

1. Create a new implementation of AbstractFunctionParser that parses and validates your custom function syntax within JSON requests. (APIJSONORM/src/main/java/apijson/orm/AbstractFunctionParser.java)
2. Define a ScriptExecutor implementation (or extend JavaScriptExecutor) if your functions require dynamic script evaluation. (APIJSONORM/src/main/java/apijson/orm/script/JavaScriptExecutor.java)
3. Register your function parser in ObjectParser.parse() method to intercept and handle custom function syntax. (APIJSONORM/src/main/java/apijson/orm/ObjectParser.java)
4. Add a corresponding Function model class to represent function metadata and configuration. (APIJSONORM/src/main/java/apijson/orm/model/Function.java)

Add Request/Response Middleware or Hooks

1. Implement the OnParseCallback interface to inject pre-parse or post-parse hooks into the parsing pipeline. (APIJSONORM/src/main/java/apijson/orm/OnParseCallback.java)
2. Register your callback in AbstractParser.parse() method by adding it to the callback chain. (APIJSONORM/src/main/java/apijson/orm/AbstractParser.java)
3. Use Entry and Pair utility classes to manipulate request/response data within your callback. (APIJSONORM/src/main/java/apijson/orm/Entry.java)
4. Handle exceptions with custom domain exceptions defined in the exception package. (APIJSONORM/src/main/java/apijson/orm/exception)

No visible Maven profile setup for different database backends, so verify your database JDBC driver is in the classpath when running. AbstractSQLConfig uses dialect-specific SQL syntax (window functions, JSON operators, pagination)—test thoroughly when switching databases. The Verifier.java security layer is extensible but not enabled by default; you must implement and configure it in AbstractVerifier subclasses or risk allowing unfiltered queries. No explicit connection pooling in the library—caller must manage HikariCP or equivalent in AbstractSQLExecutor. The pom.xml packaging is 'jar' with no standard test plugin configured; ensure tests are run separately or not at all in CI.

• Schema-Driven API Generation — APIJSON's core innovation—it generates REST endpoints directly from database schema introspection, eliminating the need to manually code CRUD endpoints, making this concept essential to understanding the library's value proposition
• Declarative Query Language (vs Imperative) — Clients send JSON describing what data they want (declarative) rather than calling imperative endpoint chains; this is why ObjectParser must transform JSON intent into SQL, making the paradigm shift critical to learning APIJSON
• SQL Dialect Abstraction — AbstractSQLConfig exists to handle MySQL vs PostgreSQL vs Oracle syntax differences transparently; understanding this pattern is essential for adding new database support or debugging dialect-specific bugs
• Template Method Pattern — AbstractParser and AbstractSQLConfig use Template Method to define the parsing/execution pipeline skeleton while letting subclasses override specific steps; this pattern pervades the codebase and must be understood to extend it
• Visitor Pattern for AST Traversal — Visitor.java enables custom logic (security checks, logging, metrics) to walk the parsed request AST without modifying parser code; crucial for implementing plugins or cross-cutting concerns
• Nested/Recursive Subqueries — APIJSON allows nested JSON requests that translate to SQL subqueries or JOINs; understanding how ObjectParser.parse() recurses through nested JSONMap structures is key to grasping multi-level data fetching
• Role-Based Access Control (RBAC) in ORM Context — AbstractVerifier and Visitor pattern enable row-level and column-level security before SQL execution; this is how APIJSON prevents unauthorized data leaks and is non-obvious in typical ORMs

• PostgREST/postgrest — Also auto-generates REST APIs from database schemas, but for PostgreSQL only; APIJSON is the multi-database equivalent with more flexible request syntax
• graphql-engine/graphql-engine — Hasura provides zero-code GraphQL APIs from databases; APIJSON achieves similar no-code goal but with JSON request payloads instead of GraphQL queries
• dreamhead/moco — Chinese-originated open-source project like APIJSON; Moco is a mock server framework, complementary for API testing against APIJSON-generated endpoints
• Tencent/APIJSON-Demo — Official example implementations and reference applications across multiple databases (MySQL, PostgreSQL, SQLServer, Oracle) showing real APIJSON integration patterns
• spring-projects/spring-data-jpa — Traditional ORM alternative for Java; APIJSON replaces hand-coded repository methods with declarative JSON, avoiding Spring Data boilerplate entirely

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for AbstractSQLConfig and SQLConfig SQL generation

The AbstractSQLConfig.java and SQLConfig.java classes are critical for translating JSON requests into SQL queries, but there are no visible test files in the repo structure. Given this is an ORM library where SQL correctness is paramount, unit tests covering various SQL generation scenarios (joins, filters, aggregations, subqueries) would catch regressions and improve maintainability. This is especially important for the orm/ package which handles core query logic.

• [ ] Create APIJSONORM/src/test/java/apijson/orm/ directory structure
• [ ] Add AbstractSQLConfigTest.java with tests for basic SELECT/INSERT/UPDATE/DELETE generation
• [ ] Add SQLConfigTest.java with tests for complex scenarios: JOIN operations, WHERE conditions, subqueries (Subquery.java), and functions (FunctionParser.java)
• [ ] Add test fixtures for different database types (MySQL, PostgreSQL via PgAttribute.java and PgClass.java)
• [ ] Ensure tests cover edge cases like NULL handling and special characters in values

Add unit tests for Verifier.java and AbstractVerifier.java authorization logic

The Verifier and AbstractVerifier classes handle access control and authorization decisions (as evidenced by Access.java model and NotLoggedInException in the exception package). These security-critical components require robust testing to prevent authorization bypass vulnerabilities. Currently, no test files are visible for this core security functionality.

• [ ] Create APIJSONORM/src/test/java/apijson/orm/VerifierTest.java
• [ ] Add tests for Access.java model validation (checking table/column permissions)
• [ ] Add tests for different user roles and their permission inheritance
• [ ] Add tests for NotLoggedInException and NotExistException scenarios
• [ ] Add tests verifying that Visitor.java context is properly validated during authorization checks

Add integration tests for ObjectParser.java with end-to-end JSON request/response cycles

ObjectParser.java is the main entry point for parsing JSON requests into database queries and responses. Without visible integration tests, contributors can't verify that the full pipeline (JSONRequest → ObjectParser → SQL execution → JSONResponse) works correctly. Adding integration tests would provide a safety net for refactoring and help new contributors understand the request lifecycle.

• [ ] Create APIJSONORM/src/test/java/apijson/orm/integration/ directory
• [ ] Add ObjectParserIntegrationTest.java with test fixtures (in-memory H2 database)
• [ ] Add test cases for: simple GET requests, nested object queries, array queries, and filtered responses
• [ ] Add tests for error scenarios using custom exceptions (ConflictException, OutOfRangeException, etc.)
• [ ] Add tests verifying that response structure matches JSONResponse.java expected format with proper error handling

• Add unit tests for apijson/orm/SQLConfig.java under src/test/java covering each supported database type (MySQL, PostgreSQL, Oracle, SQLServer); currently the test directory structure is missing from the repo, which is a significant testing gap for an ORM.
• Document the Visitor pattern implementation in apijson/orm/Visitor.java with concrete examples of custom visitor implementations (e.g., query logging, metric collection) in a new docs/VISITOR_GUIDE.md file, since the current javadoc-only approach leaves the extension points unclear.
• Implement missing database dialect support in AbstractSQLConfig for CockroachDB and openGauss (both listed in the badge matrix) by extracting dialect-specific logic into new SQLConfig subclasses and adding integration tests with Docker containers running those databases.

• High · SQL Injection Risk in Dynamic Query Building — APIJSONORM/src/main/java/apijson/orm/SQL.java, AbstractSQLConfig.java, AbstractSQLExecutor.java, SQLExecutor.java. The codebase contains SQL.java and AbstractSQLConfig.java which suggest dynamic SQL query construction. ORM libraries that build SQL from user input are vulnerable to SQL injection attacks if input is not properly sanitized. The presence of AbstractSQLExecutor.java and SQLExecutor.java indicates raw SQL execution paths. Fix: Ensure all SQL queries use parameterized prepared statements with bound parameters. Implement strict input validation and whitelist allowed columns/tables. Add comprehensive unit tests for SQL injection vectors.
• High · No Dependencies Declared - Potential Missing Security Updates — APIJSONORM/pom.xml. The pom.xml file shows an empty <dependencies> section with no external library declarations. This is unusual for an ORM library and suggests either: (1) dependencies are managed elsewhere, (2) the library uses legacy approaches, or (3) there's a build configuration issue. This makes it difficult to track security vulnerabilities in transitive dependencies. Fix: Declare all direct dependencies explicitly in pom.xml with specific versions. Use dependency management tools (OWASP Dependency-Check, Snyk) to monitor for known vulnerabilities. Keep Maven plugins updated to latest versions.
• High · Unsafe Script Execution Detected — APIJSONORM/src/main/java/apijson/orm/script/JSR223ScriptExecutor.java, JavaScriptExecutor.java. The presence of JSR223ScriptExecutor.java and JavaScriptExecutor.java in the codebase indicates support for arbitrary script execution. This is a critical security risk if user-supplied code can be executed without proper sandboxing. Dynamic code evaluation from user input can lead to Remote Code Execution (RCE). Fix: If script execution is necessary, implement strict sandboxing using security managers. Whitelist allowed script functions and disable dangerous operations. Never execute user-supplied scripts directly. Use read-only contexts with restricted API access. Consider removing script execution if not essential.
• High · Potential Insecure Reflection Usage — APIJSONORM/src/main/java/apijson/MethodAccess.java. The MethodAccess.java class suggests reflection-based method invocation. Reflection combined with user input can bypass access controls and invoke unintended private methods or constructors, leading to unauthorized access or privilege escalation. Fix: Implement strict whitelist validation for any reflection operations. Verify that only explicitly allowed methods/classes can be invoked. Use SecurityManager to restrict reflection capabilities. Log all reflection invocations for audit trails.
• Medium · Missing Input Validation Framework — APIJSONORM/src/main/java/apijson/JSONRequest.java, JSONResponse.java, JSONParser.java. While NotNull.java exists, there's no evidence of comprehensive input validation. The JSONRequest.java and JSONResponse.java classes suggest data transformation without obvious validation layers. This can lead to various injection attacks (XSS, command injection, path traversal). Fix: Implement comprehensive input validation for all user inputs. Validate data types, lengths, and formats. Use established validation libraries. Implement output encoding for different contexts (SQL, HTML, JavaScript). Add validation at entry points.
• Medium · No Visible Authentication/Authorization Checks — APIJSONORM/src/main/java/apijson/orm/Verifier.java, AbstractVerifier.java, APIJSONORM/src/main/java/apijson/orm/model/Access.java. The Verifier.java and AbstractVerifier.java suggest some verification logic, but the model classes (Access.java) indicate access control. However, there's no evidence of comprehensive authentication framework or role-based access control in the visible structure. Fix: Implement robust authentication using standard frameworks (OAuth 2.0, JWT). Ensure all API endpoints require proper authentication. Implement fine-grained authorization checks for database operations. Log authentication failures and access denials.
• Medium · Information Disclosure Risk in Exceptions — undefined. Custom exception classes (CommonException, ConditionErrorException, etc.) are defined but without visibility into their implementation. Improper error handling can leak sensitive information about database schema, internal structure, or stack traces to Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.