Request Methods and Structure

Relevant source files

• APIJSONORM/src/main/java/apijson/RequestMethod.java
• APIJSONORM/src/main/java/apijson/orm/Operation.java
• Document-Chinese.md
• Document.md

Purpose and Scope

This page covers the technical specification of APIJSON request methods (get, gets, head, heads, post, put, delete, crud), request structural components (tags, table names, and array containers like TableName[]), and special array control keywords (count, page, query, join). It details how the protocol defines operations and how requests are structured before being processed by the backend parser pipeline.

Sources: APIJSONORM/src/main/java/apijson/RequestMethod.java:1-115 Document.md:1-258

---

1. Request Methods (RequestMethod)

APIJSON extends standard HTTP / REST methods by introducing secure / private counterparts (GETS, HEADS) and a meta-method (CRUD), mapping them to internal execution logic via the RequestMethod enumeration.

+-----------------------------------------------------------------+
|                       RequestMethod Enum                        |
|                                                                 |
|  [GET]  --> Public standard data retrieval                      |
|  [GETS] --> Private/secure retrieval via POST body              |
|  [HEAD] --> Public metadata / count check                       |
| [HEADS] --> Private metadata check via POST body                |
|  [POST] --> Resource insertion / creation                       |
|   [PUT] --> Resource modification                               |
|[DELETE] --> Resource removal                                    |
|  [CRUD] --> Multi-statement batch execution                     |
+-----------------------------------------------------------------+

Method Categories and Behavior

• GET / HEAD (Public Methods): Open, plaintext methods where the request structure can be directly accessed via URL query parameters or browser navigation (RequestMethod.isPublicMethod).
• GETS / HEADS (Private Methods): Secure counterparts to GET and HEAD. They transmit the request JSON inside a POST request body to hide request parameters and enforce strict request structure verification (RequestMethod.isPrivateMethod).
• POST / PUT / DELETE (Update Methods): Standard mutation methods for creating, updating, and deleting records (RequestMethod.isUpdateMethod).
• CRUD: Batch command container allowing multiple independent or chained statements, queries, updates, and remote function invocations within a single atomic transmission.

Sources: APIJSONORM/src/main/java/apijson/RequestMethod.java:14-110

---

2. Request Structure: Tables, Tags, and Arrays

An APIJSON request is a JSON object where top-level keys represent either table models (e.g., "User", "Moment"), array containers (e.g., "[]", "Comment[]"), or operation tags.

Structure Breakdown

1. Table Objects: Keys matching database table names (or mapped model classes) containing column fields, comparison operators, and assignment expressions.
2. Array Containers ([] / TableName[]): Unnamed arrays ("[]") or table-specific arrays ("Comment[]") used to query or mutate multiple records. Table-specific arrays unwrap the object wrapper automatically in responses.
3. Tags: Metadata fields or routing identifiers that categorize requests for permission checks and schema validation.

+-----------------------------------------------------------------+
|                        Request JSON Root                        |
|                                                                 |
|  Root Object                                                    |
|  ├── "[]" (Array Container)                                     |
|  │    ├── "page": 0                                             |
|  │    ├── "count": 2                                            |
|  │    ├── "Moment": { "content$": "%a%" }                       |
|  │    └── "User": { "id@": "/Moment/userId" }                   |
|  └── "User" (Single Table Object)                               |
|       └── "id": 38710                                           |
+-----------------------------------------------------------------+

Sources: Document.md:46-160, APIJSONORM/src/main/java/apijson/orm/Operation.java:11-165

---

3. Array Control Keywords

When querying or manipulating arrays via "[]" or "TableName[]", specific control keywords govern pagination, search limits, subquery association, and JOIN behavior.

Keyword	Type	Description
count	Number	Limits the maximum number of records returned in the array query.
page	Number	Zero-based index for pagination offset (offset = page * count).
query	Number / String	Controls query strategy (e.g., whether to execute a separate count query or total calculation).
join	String / Array	Explicitly defines table joins or relationship linking paths.

Example Request Utilizing Array Keywords

Sources: Document.md:48-57, APIJSONORM/src/main/java/apijson/RequestMethod.java:1-115

---

4. Architecture to Code Entity Mapping

The following diagrams bridge the conceptual request structure and HTTP methods to their concrete Java implementations within the APIJSON codebase.

Diagram 1: Request Method Routing to Code Entities

Sources: APIJSONORM/src/main/java/apijson/RequestMethod.java:14-115, Document.md:1-258

Diagram 2: Request Structure to Parser Components

Sources: APIJSONORM/src/main/java/apijson/orm/Operation.java:11-165, Document.md:46-160