Creating a New API Definition

Creating an API Definition allows you to describe an endpoint once and reuse it consistently across tests, environments, and teams. This page is where you define how the request is built, how it authenticates, and what inputs it expects.

Why it matters

Single source of truth: Every test that uses this API relies on the same definition.
Fewer errors: Parameters, authentication, and body structure are defined clearly in one place.
Faster onboarding: New team members understand how an API works without reading backend code.

When to use it

You want to register a new endpoint before using it in test cases.
You need to standardize how an API is called across multiple tests.
You want to validate an endpoint quickly using Run Test before saving or reusing it.

Core concepts

API Definition – a reusable description of an HTTP request (endpoint, method, auth, timeout).
Parameter – a named input mapped to a specific request location (Query, Path, Header, Body, Cookie).
Body Mode – controls whether the request body is built from parameters or sent as raw JSON.

How it works

You fill in the core API fields (name, endpoint, method, authentication).
You define how the request body is built (Parameters or Raw JSON).
You add parameters that describe all expected inputs.
You can test the API immediately before or after saving it.

How to use it

Step 1: Open the “Add new API” page

Navigate to API Manager → Add new. This opens the API creation form.

Step 2: Fill in the basic information

Name: A clear, human-readable name (e.g. Users – Get by ID).
Description: What this API does and when it should be used.
Endpoint: The relative path of the endpoint (e.g. /users/{id}).
Version (optional): A label to distinguish variations or iterations.
Method: The HTTP verb used by the endpoint.

Step 3: Choose authentication

Select how the API authenticates (None, API Key, Bearer Token, or OAuth2).
Only the fields relevant to the selected option are shown.

Note

Select how the API authenticates (None, API Key, Bearer Token, or OAuth2).
Only the fields relevant to the selected option are shown.

Step 4: Configure timeout

Optionally define a timeout (in milliseconds) to control how long the request may run before stopping.

Step 5: Choose how the request body is built

Parameters mode
Use this when the body is composed of individual fields. Body parameters can have default values and can be overridden during testing.
Raw JSON mode
Use this for complex or nested payloads (such as GraphQL). In this mode, Body parameters are disabled and ignored.

Step 6: Add parameters

For each expected input, add a parameter and define:

Name
Location (Query, Path, Header, Cookie, Body)
Required flag
Type (String, Integer, Boolean, Array, Object)
Description
Default Value (Body parameters only)

You can add or remove parameters dynamically as needed.

Step 7: Test the API before saving

Use Test This API at the bottom of the page:

Enter values for parameters.
Click Run Test.
Review the response directly in the page.

This lets you validate the definition before committing it.

Step 8: Create the API

Click Create to save the API Definition and make it available for reuse across the project.

Best practices

Use consistent naming (Group – Action – Detail) to keep APIs easy to find.
Keep parameter names aligned with the actual API contract.
Prefer Parameters mode unless Raw JSON is truly required.
Always test the API once before using it in test cases.

Common mistakes

❌ Mistake 1: Putting body fields in Raw JSON while still defining Body parameters
✔ Fix: Use either Parameters mode or Raw JSON mode, not both.

❌ Mistake 2: Forgetting to define Path parameters used in the endpoint
✔ Fix: Every {placeholder} in the endpoint should have a matching Path parameter.

Security & permissions

API Definitions are created within the active project and follow project access rules.
Authentication values are handled securely through the interface
Only authorized users can create or modify API Definitions.

AXQA

Did You Know?