JSON Processing: HTTP/1.1 vs HTTP/2 Architecture

Overview

Axis2/C supports JSON processing through two distinct architectures:

Aspect	HTTP/1.1 JSON	HTTP/2 JSON
Source Files	`axis2_json_reader.c`, `axis2_json_writer.c`	`axis2_h2_transport_utils.c`
JSON Library	json-c	json-c
Internal Format	AXIOM XML tree (`axiom_node_t*`)	Native JSON (`json_object*`)
SOAP Handling	Full SOAP envelope processing	Minimal dummy envelope (bypassed)
Performance	Slower (JSON↔AXIOM conversion)	Faster (direct JSON processing)
Recommendation	Legacy/backward compatibility	Recommended for new development

Architecture Diagrams

HTTP/1.1 JSON Processing Path

┌─────────────┐     ┌──────────────────────┐     ┌─────────────────┐     ┌─────────────┐
│ JSON Input  │────▶│ axis2_json_reader.c  │────▶│ axiom_node_t*   │────▶│ SOAP/Engine │
│             │     │ (json-c parsing +    │     │ (XML tree)      │     │ Processing  │
│             │     │  AXIOM conversion)   │     │                 │     │             │
└─────────────┘     └──────────────────────┘     └─────────────────┘     └─────────────┘
                              │
                              ▼
                    ┌──────────────────────┐
                    │ axis2_json_read_node │
                    │ (recursive JSON→XML) │
                    └──────────────────────┘

Key Functions:

axis2_json_reader_create_for_memory() - Creates reader from JSON string
axis2_json_reader_read() - Parses JSON and converts to AXIOM tree
axis2_json_reader_get_root_node() - Returns axiom_node_t* (NOT json_object*)

HTTP/2 JSON Processing Path

┌─────────────┐     ┌──────────────────────┐     ┌─────────────────┐     ┌─────────────┐
│ JSON Input  │────▶│ json_tokener_parse() │────▶│ json_object*    │────▶│ Service     │
│             │     │ (direct json-c)      │     │ (native JSON)   │     │ Handler     │
└─────────────┘     └──────────────────────┘     └─────────────────┘     └─────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────────┐
                                               │ Minimal SOAP Envelope│
                                               │ (framework compat,   │
                                               │  processing bypassed)│
                                               └─────────────────────┘

Key Functions:

json_tokener_parse() - Direct json-c parsing
axis2_h2_transport_utils_process_http_post_request() - HTTP/2 JSON handler
No AXIOM conversion - JSON stays as json_object*

Performance Comparison

HTTP/1.1 JSON Overhead

The HTTP/1.1 path incurs significant overhead because:

Double Parsing: JSON is parsed by json-c, then converted to AXIOM XML
Memory Allocation: AXIOM tree requires additional memory for XML nodes
Recursive Conversion: axis2_json_read_node() recursively builds XML tree
Type Mapping: JSON types must be mapped to AXIOM element types

/* HTTP/1.1: JSON → AXIOM conversion (axis2_json_reader.c) */
axis2_status_t axis2_json_read_node(
    json_object* parent,      /* Input: JSON object */
    const char* name,
    axiom_node_t** om_node,   /* Output: AXIOM XML node */
    const axutil_env_t* env)
{
    /* Recursive conversion of every JSON element to XML */
    json_object_object_foreach(parent, key, value) {
        /* Create AXIOM element for each JSON key */
        /* Recursively process nested objects/arrays */
    }
}

HTTP/2 JSON Efficiency

The HTTP/2 path eliminates conversion overhead:

Single Parse: JSON is parsed once by json-c
Native Access: Services access json_object* directly
No Conversion: No AXIOM tree creation
Minimal Envelope: Dummy SOAP envelope satisfies framework without processing

/* HTTP/2: Direct JSON processing (axis2_h2_transport_utils.c) */
axis2_status_t axis2_h2_transport_utils_process_http_post_request(
    const axutil_env_t* env,
    axutil_stream_t* in_stream,
    const axis2_char_t* content_type)
{
    /* Parse JSON directly - no conversion */
    json_obj = json_tokener_parse(json_string);

    /* Service receives json_object* directly */
    /* No AXIOM overhead */
}

The Dummy SOAP Envelope Architecture

HTTP/2 mode uses a “dummy SOAP envelope” pattern (similar to Axis2/Java):

Framework Compatibility: Axis2/C core expects SOAP message context
Minimal Overhead: Empty/minimal envelope created for framework satisfaction
Processing Bypass: IS_JSON_STREAM=true flag signals JSON-only mode
Direct Access: JSON Message Receiver bypasses SOAP processing entirely

This achieves framework compatibility with near-zero overhead.

When to Use Each Path

Use HTTP/2 JSON (Recommended)

New service development
High-performance JSON APIs
RESTful services
Microservices architecture
Large payload processing
HTTP/2 multiplexed streams

Use HTTP/1.1 JSON (Legacy)

Existing services requiring backward compatibility
Integration with systems that only support HTTP/1.1
When AXIOM/XML interoperability is needed
Legacy deployment environments

History and Rationale

HTTP/1.1 JSON Support

Origin: Community contributed feature (original Axis2/C JSON support)
Design: Built on top of existing AXIOM infrastructure
Trade-off: Easier integration with existing code, but performance penalty
Status: Maintained for backward compatibility, not recommended for new development

HTTP/2 JSON Support

Origin: HTTP/2 Pure JSON Architecture redesign
Design: Direct json-c usage with minimal SOAP envelope
Trade-off: Better performance, requires HTTP/2 infrastructure
Status: Recommended for all new JSON service development

Fuzzer Coverage

Both JSON paths are tested by dedicated fuzzers:

Fuzzer	Tests	Entry Point
`fuzz_json_reader`	HTTP/1.1 JSON→AXIOM	`axis2_json_reader_create_for_memory()`
`fuzz_json_parser`	HTTP/2 direct json-c	`json_tokener_parse()`

See fuzz/fuzz_json_reader.c and fuzz/fuzz_json_parser.c for implementation details.