Planned Features

Relevant source files

• Roadmap.md

This document details upcoming and recently implemented features for APIJSON. The features are organized by implementation status and technical area. This roadmap focuses on new functionality and protocol enhancements. For performance and security improvements, see Performance and Security Improvements. For stability and testing plans, see Stability and Testing.

The planned features follow three core principles outlined in Roadmap.md12-15:

1. Must address real application scenarios, not pseudo-requirements
2. Should not be redundant with existing functionality (remote functions, @raw, etc.)
3. Must not break or complicate existing features

---

Feature Status Overview

The following table summarizes all planned features and their current implementation status:

Feature	Status	Version	Primary Component	Notes
Fake Delete	✅ Completed	-	AbstractSQLConfig	Contributed by @cloudAndMonkey
@having&	✅ Completed	5.0.0	AbstractSQLConfig	AND-connected HAVING clauses
@column!	✅ Plugin Available	-	apijson-column	Field exclusion via plugin
TSQL @explain	🟡 Partial	-	AbstractSQLExecutor	Oracle supported, SQL Server issues
page from 1	📋 Planned	-	AbstractParser	Add DEFAULT_QUERY_PAGE
@url Distribution	📋 Planned	-	AbstractParser	Forward requests to other servers
UNION Support	📋 Planned	-	AbstractSQLConfig	Convert OR to UNION queries
WITH Clause	✅ Completed	-	AbstractSQLConfig	Contributed by @cloudAndMonkey
id + Other Conditions	📋 Planned	-	AbstractVerifier	Flexible delete/update conditions

Sources: Roadmap.md7-240

---

Completed Features

Fake Delete (Soft Delete)

Status: Implemented
Pull Request: #493

Physical deletion is rarely used in production systems. Instead, records are marked as deleted using fields like is_deleted and filtered in CRUD operations.

Implementation Mechanism:

Key Methods:

• SQLConfig.isFakeDelete() - Returns whether table uses fake delete Roadmap.md23
• SQLConfig.onFakeDelete(Map<String, Object> map) - Adds deletion conditions Roadmap.md24-29
  • GET: map.put("deleted", 0) - Only show non-deleted
  • PUT: map.put("deleted", 0) - Only update non-deleted
  • DELETE: map.put("deleted", 1) - Mark as deleted
  • POST: No processing needed

Framework Integration:

The apijson-framework layer can support automatic configuration via the Access table with fields: deletedKey, deletedValue, notDeletedValue Roadmap.md32-33

Sources: Roadmap.md17-33

---

@having& (AND-Connected HAVING)

Status: Implemented in 5.0.0
Release: 5.0.0

Implements internal AND connections for HAVING clauses, maintaining consistency with the "horizontal OR, vertical AND" principle. The original @having now uses OR connections internally.

Behavior:

Keyword	Connection Logic	Example
@having	OR between conditions	"@having": {"count(*)>": 1, "sum(amount)>": 1000} → (count(*) > 1 OR sum(amount) > 1000)
@having&	AND between conditions	"@having&": {"count(*)>": 1, "sum(amount)>": 1000} → (count(*) > 1 AND sum(amount) > 1000)

Sources: Roadmap.md35-40

---

@column! (Field Exclusion)

Status: Plugin available: apijson-column

Provides field name mapping and exclusion using !key syntax. This is only supported in apijson-framework and requires configuring all fields per interface version and table.

Configuration Options:

1. HashMap Configuration - Code-based field definitions
2. VersionedColumn Table - Database records for field configuration Roadmap.md46

Conflict Resolution:

When both @column (inclusion) and @column! (exclusion) are present:

• No overlapping fields → Ignore @column!, only apply @column
• Overlapping fields exist → Throw exception, return error code and message Roadmap.md47-49

Sources: Roadmap.md42-49

---

WITH Clause Support

Status: Implemented
Pull Request: #481
Contributor: @cloudAndMonkey

Reduces subquery execution count and improves performance by using Common Table Expressions (CTE).

Example Request:

Generated SQL Transformation:

The subquery in the WITH clause is executed once and reused across multiple queries, improving performance when the same subquery appears in multiple table operations Roadmap.md123

Sources: Roadmap.md119-168

---

In Progress Features

TSQL @explain Support

Status: Partially implemented - Oracle works, SQL Server has issues
Pull Request: #434

APIJSON supports Oracle, SQL Server, and DB2 TSQL databases. However, "@explain": true currently uses SET STATISTICS PROFILE ON, which has problematic behavior:

• SELECT results go to default ResultSet
• Performance analysis goes to moreResult

This makes @explain unusable for SQL Server and DB2. Oracle EXPLAIN is now supported Roadmap.md51-58

Affected Components:

• AbstractSQLConfig
• AbstractSQLExecutor

Sources: Roadmap.md51-58

---

Planned Features

Page Numbering Starting from 1

Status: Planned
Target Components: Parser, AbstractParser, AbstractSQLConfig

Currently, pagination only supports starting from page 0. Supporting page 1 as the default is more intuitive and widely adopted.

Proposed Changes:

Implementation Plan:

1. Add DEFAULT_QUERY_PAGE constant to Parser Roadmap.md62
2. Add getDefaultQueryPage() method, similar to getDefaultQueryCount() Roadmap.md62-63
3. Update AbstractParser and AbstractSQLConfig to adjust page offset calculations Roadmap.md65
4. Maintain backward compatibility - both page 0 and page 1 should work

Benefits:

• Frontend can directly use page numbers without conversion
• info.page values match displayed page numbers Roadmap.md64

Sources: Roadmap.md60-65

---

Distributed Queries with @url

Status: Planned
Target Component: AbstractParser

Forward requests to other servers using the @url keyword, enabling distributed query execution across multiple APIJSON instances.

Example Request:

Processing Model:

Key Design Decisions:

1. Synchronous Processing: Must process synchronously due to reference dependency ("userId@": "User/id") Roadmap.md83
2. Asynchronous Option: Could add ~ prefix for async: "@url": "~http://apijson.cn:8080/get" when caller guarantees no downstream dependencies Roadmap.md84

Sources: Roadmap.md67-85

---

UNION Support

Status: Planned
Target Component: AbstractSQLConfig

Convert OR-connected conditions to UNION queries to leverage database indexes, improving query performance.

Motivation:

While INNER JOIN + OR conditions can replace UNION functionality, it cannot match UNION's ability to use indexes effectively Roadmap.md89

Proposed Syntax:

@union Values:

• 0 - Do not use UNION (default)
• 1 - Use UNION
• 2 - Use UNION ALL (if implementation is simple) Roadmap.md92

SQL Transformation:

The @combine fields are split into N separate SQL queries connected by UNION, where N is the number of OR-connected fields Roadmap.md100

Sources: Roadmap.md87-117

---

Flexible Delete/Update Conditions

Status: Planned
Target Components: AbstractVerifier, Operation

Currently, AbstractVerifier.IS_UPDATE_MUST_HAVE_ID_CONDITION forces id as a required condition for updates/deletes. This feature will allow:

1. Using id OR other fields as conditions
2. Using id AND other fields simultaneously
3. Configurable via Request table

Current Limitation:

Proposed Solution 1: Multiple Request Table Entries

Clients specify which rule to use via different tag values Roadmap.md189-200

Proposed Solution 2: Extended MUST Syntax

Add OR logic to MUST using pipe | with spaces:

Extended Syntax Options:

Syntax	Meaning	Example
"1:id | date"	Exactly 1 must be provided	"MUST": "1:id | date"
"2+:id | momentId|{} | date>="	At least 2 must be provided	"MUST": "2+:id | momentId|{} | date>="
"2-:id | momentId|{} | date>="	At most 2 can be provided	"MUST": "2-:id | momentId|{} | date>="

Important: Left and right of | must have spaces to avoid conflicts with suffixes like "name|$", "id|{}" Roadmap.md219

Implementation Changes:

Conflict Handling:

Must handle mutual exclusivity between REFUSE and MUST Roadmap.md233-234

Sources: Roadmap.md176-238

---

Not Implementing

CASE Support

Status: Not implementing
Rationale: Can be achieved using @raw with standard SQL CASE WHEN syntax Roadmap.md171

Instead of creating custom APIJSON syntax for CASE WHEN THEN statements, users can write SQL directly:

Sources: Roadmap.md170-173

---

Feature Request Principles

All feature requests are evaluated against these criteria Roadmap.md12-15:

1. Real Scenarios Required: Must address actual application needs, not pseudo-requirements. Provide examples.

2. No Redundancy: If remote functions or existing features like @raw can implement the functionality well, no new feature is added.

3. Backward Compatibility: Cannot break or complicate existing functionality.

How to Request Features:

• Open an issue on GitHub with use case examples
• Test on APIAuto (Account: 13000002020, Password: 123456)
• Discuss on community channels

Sources: Roadmap.md12-15

---

Feature Implementation Architecture

The following diagram shows which components are typically affected when adding new features:

Sources: Roadmap.md1-398

---

Related Documentation

• Protocol Specification: See APIJSON Protocol for current protocol details
• ORM Architecture: See Core ORM Architecture for extension points
• Security: See Security and Access Control for security-related features
• Performance: See Performance and Security Improvements for optimization plans
• Testing: See Stability and Testing for quality assurance plans

Sources: Roadmap.md1-398