151 lines
5.0 KiB
Plaintext
151 lines
5.0 KiB
Plaintext
SECTION II: Input and Output (I/O) Management
|
||
|
||
This section describes the mechanisms AVAP uses for external data ingestion, parameter integrity validation, and construction of the response payload delivered to the final client.
|
||
|
||
2.1 Intelligent Parameter Capture (addParam)
|
||
|
||
The addParam command is responsible for extracting information from the incoming HTTP request. Its design is source-agnostic, simplifying development by not requiring the programmer to specify where the data originates.
|
||
|
||
Interface
|
||
addParam(param_name, target_variable)
|
||
Priority Mechanism (Cascading Search)
|
||
|
||
When addParam is invoked, the AVAP engine inspects the request in the following hierarchical order:
|
||
|
||
Query Arguments:
|
||
Parameters present in the URL (e.g., ?id=123).
|
||
|
||
JSON Body:
|
||
If the request includes Content-Type: application/json, the engine searches for the key inside the JSON object.
|
||
|
||
Form Data / Body Arguments:
|
||
Data submitted via standard forms (x-www-form-urlencoded).
|
||
|
||
Technical Behavior
|
||
|
||
Automatic Decoding:
|
||
The engine attempts to decode values into ASCII/UTF-8 format, eliminating encoding inconsistencies.
|
||
|
||
Null Handling:
|
||
If the requested parameter does not exist in any source, the target variable is initialized as None. This enables subsequent security checks using if blocks.
|
||
|
||
2.2 Collection Validation and Counting (getListLen)
|
||
|
||
To ensure API robustness, it is necessary to validate the volume of received information. getListLen acts as AVAP’s volume inspector.
|
||
|
||
Interface
|
||
getListLen(source_variable, target_variable)
|
||
I/O Applications
|
||
|
||
Parameter Validation:
|
||
Counts how many elements are contained in a variable populated by addParam or getQueryParamList.
|
||
|
||
Loop Safety:
|
||
Before initiating a startLoop, it is recommended to use getListLen to define the upper bound of the iteration, preventing overflow errors.
|
||
|
||
Database Results:
|
||
After a query, determines whether records were retrieved (length > 0) or if the result set is empty.
|
||
|
||
2.3 Multiple List Capture (getQueryParamList)
|
||
|
||
There are scenarios where the same parameter is sent multiple times (e.g., search filters such as ?color=red&color=blue). AVAP manages this through specialized list-based capture.
|
||
|
||
Interface
|
||
getQueryParamList(param_name, target_list_variable)
|
||
Effect
|
||
|
||
Transforms all occurrences of param_name into a structured list within target_list_variable. If only one value is present, a single-element list is created. This ensures downstream logic can always treat the data as a collection, preventing type errors.
|
||
|
||
2.4 Response Construction (addResult)
|
||
|
||
The addResult command registers which variables will be included in the response body. AVAP dynamically constructs an output JSON object based on calls to this command.
|
||
|
||
Interface
|
||
addResult(source_variable)
|
||
Advanced Features
|
||
|
||
Promise Handling:
|
||
If the variable passed to addResult is the result of an operation initiated with go_async, the engine automatically marks that field as "promised" in the response or returns the thread ID if synchronization has not completed.
|
||
|
||
String Cleanup:
|
||
The engine detects redundant quotation marks (resulting from prior evaluations) and normalizes them to ensure the resulting JSON is valid and clean.
|
||
|
||
Multi-Registration:
|
||
Multiple calls to addResult are allowed. Each call adds a new key to the output JSON object. By default, the JSON key matches the variable name, unless a custom key is defined in the engine.
|
||
|
||
2.5 HTTP Status Control (_status)
|
||
|
||
AVAP uses a reserved system variable to communicate with the underlying web server and define the success or error code of the transaction.
|
||
|
||
Using _status
|
||
|
||
By assigning a numeric value to the _status variable (using addVar or direct assignment), the programmer defines the HTTP response code.
|
||
|
||
Code Common Usage in AVAP
|
||
200 Successful operation (default value).
|
||
201 Resource successfully created.
|
||
400 Parameter validation error (Bad Request).
|
||
401 Authentication failure.
|
||
500 Internal error caught inside an exception block.
|
||
|
||
Integrated Example of Section II
|
||
// Capture input
|
||
addParam("user_id", id)
|
||
|
||
// Validate presence
|
||
if(id, None, '==')
|
||
addVar(_status, 400)
|
||
addVar(error, "User ID is required")
|
||
addResult(error)
|
||
return()
|
||
end()
|
||
|
||
// If execution reaches here, respond with success
|
||
addVar(_status, 200)
|
||
addResult(id)
|
||
|
||
Examples
|
||
|
||
1. ID Capture
|
||
|
||
(Input Ingestion – Section 2.1)
|
||
|
||
addParam("client_id", internal_id)
|
||
// If the client sends ?client_id=500, internal_id will be 500
|
||
addResult(internal_id)
|
||
|
||
2. Parameter Counter
|
||
|
||
(Collection Validation – Section 2.2)
|
||
|
||
addParam("data_list", my_list)
|
||
getListLen(my_list, count)
|
||
addResult(count)
|
||
|
||
3. Null Validation
|
||
|
||
(Input Validation & HTTP Status Control – Sections 2.1 & 2.5)
|
||
|
||
addParam("api_key", key)
|
||
if(key, None, "==")
|
||
addVar(_status, 403)
|
||
addVar(error, "Access denied: missing API KEY")
|
||
addResult(error)
|
||
end()
|
||
|
||
4. Multiple List Capture
|
||
|
||
(Multi-Value Query Capture – Section 2.3)
|
||
|
||
getQueryParamList("emails", email_list)
|
||
addResult(email_list)
|
||
|
||
5. Multiple Response (JSON Construction)
|
||
|
||
(Response Construction – Section 2.4)
|
||
|
||
addVar(code, 200)
|
||
addVar(status, "Success")
|
||
addResult(code)
|
||
addResult(status)
|
||
// Result: {"code": 200, "status": "Success"} |