Body Modes: Parameters vs Raw JSON

Body Modes control how the request payload is built when an API includes a body. AXQA supports two mutually exclusive modes: Parameters and Raw JSON, each designed for a different type of API request.

Why it matters

• Correct request structure: Choosing the right mode prevents malformed payloads.
• Cleaner definitions: Simple APIs stay readable, complex ones stay flexible.
• Predictable execution: Body behavior remains consistent across tests and environments.

When to use it

• Use Parameters mode for structured, field-based request bodies.
• Use Raw JSON mode for complex, nested, or non-standard payloads (such as GraphQL).
• Switch modes when the API contract changes.

Core concepts

• Body Mode – the strategy used to build the request payload.
• Parameters Mode – the body is assembled from defined Body parameters.
• Raw JSON Mode – the body is sent exactly as written, without parameter injection.

How it works

1. You select a Body Mode in the API Definition.
2. AXQA adjusts available parameter options based on the selected mode.
3. During execution, the request body is built according to the active mode.
4. The same behavior applies when testing from Add, Edit, or Inline Test views.

How to use it

Step 1: Select a Body Mode

On the API Definition page, choose one of the following:

• Parameters
• Raw JSON

Step 2: Parameters mode

In Parameters mode:

• Body parameters are enabled.
• Each Body parameter becomes a field in the request payload.
• Default values may be defined for Body parameters.
• During testing, Body inputs are generated automatically.

Step 3: Raw JSON mode

In Raw JSON mode:

• Body parameters are disabled and ignored.
• You manually provide the full JSON payload.
• The payload is sent exactly as written.

This mode is ideal for:

• GraphQL requests
• Deeply nested JSON structures
• APIs that do not map cleanly to flat parameters

Step 4: Switching between modes

• Switching to Raw JSON automatically disables Body parameters.
• Switching back to Parameters re-enables Body parameters.
• No payload data is merged between modes.

Best practices

• Default to Parameters mode unless Raw JSON is truly needed.
• Use Raw JSON only when the payload structure cannot be represented cleanly as parameters.
• Keep Raw JSON payloads minimal and well-formatted.
• Retest the API whenever you change the Body Mode.

Common mistakes

❌ Mistake 1: Expecting Body parameters to be applied in Raw JSON mode
✔ Fix: Use Parameters mode if Body parameters or defaults are required.

❌ Mistake 2: Switching modes without retesting
✔ Fix: Always run a test after changing the Body Mode.

Security & permissions

• Body content is processed according to project access rules.
• Raw JSON is treated as a single payload and not interpreted beyond execution needs.
• Only authorized users can change the Body Mode of an API Definition.

Related documentation

• Parameters in Depth
• Creating a New API Definition
• Editing an API Definition
• Testing an API