API Definitions & Parameters (Core Concepts)

API Definitions are reusable request templates you create once and use across the platform. Each definition stores the endpoint, method, authentication type, and optional metadata (schemas, examples, notes), while Parameters define how values are passed into the request.

Why it matters

• Consistency: Your team uses one shared definition instead of rewriting the same request in multiple places.
• Speed: You can test, reuse, and update APIs quickly without touching test logic everywhere.
• Clarity: Parameters make requests readable and reduce mistakes when values change between environments or builds.

When to use it

• You want a single source of truth for an endpoint used across multiple tests.
• You need to standardize requests for team collaboration (naming, description, examples).
• You’re building tests that require dynamic input (query/path/header/body values that change per run).

Core concepts

• Project – isolated workspace
  APIs are created and managed within a project context, so teams don’t mix definitions between unrelated work.
• API Definition – reusable request template
  A definition includes endpoint + method + version + authentication type, and can optionally include schemas, examples, error codes, retry policy, and notes.
• API Parameter – named input to a request
  A parameter has a name and location (Query / Path / Header / Body / Cookie). It can be required or optional, and may include a default value (commonly used for body parameters).

How it works

1. You create an API Definition for an endpoint (e.g., GET /users/{id} or POST /login).
2. You add Parameters that describe where values go (query/path/header/body/cookie).
3. When the API is executed (tested or reused), AXQA builds the final request using the definition + parameter values.
4. The latest execution info (like last status/duration/size) can be shown as quick context for the team.

How to use it

Step 1: Create an API Definition

• Give it a clear API Name (team-friendly and searchable).
• Add the Endpoint and choose the HTTPs Method.
• Optionally set a Version and a short Description to explain purpose and expected behavior.

Step 2: Add Parameters

• Add parameters for any values that change between runs or environments.

• Choose the correct location:

  • Query: ?page=1&limit=20

  • Path: /users/{id}

  • Header: Authorization, Content-Type, or custom headers

  • Body: payload fields for POST/PUT/PATCH

  • Cookie: cookie-based values when needed

• Mark parameters as Required only when the request cannot run without them.

Step 3: Choose how the body is built (when relevant)

• Use the Parameters mode here.

Best practices

• Use a consistent naming style like: Auth - Login, Users - Get By ID, Orders - Create.
• Keep parameters small and specific (avoid one big “payload” parameter unless you truly need raw JSON).
• Maintain the optional metadata (examples, error codes, notes) as a shared reference for the whole team.

Common mistakes

❌ Mistake 1: Using the wrong parameter location (e.g., putting id in Query instead of Path)
✔ Fix: Match the parameter location to how the endpoint is defined (Path placeholders go in Path).

❌ Mistake 2: Making everything “Required”
✔ Fix: Only mark as required what the endpoint truly needs; keep optional values optional to improve reuse.

Security & permissions

• API Definitions are managed within the current project context, so access depends on your project role.
• Sensitive authentication values are handled as protected fields in the system UI.
• Creation and updates are tracked so teams can understand who changed what and when.

Related documentation

• Projects
• API Testing
• Using API Definitions in Test Cases
• Authentication Types (API Key / Bearer / OAuth2)