> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Learn recommended approaches for environment strategy, variable management, approval workflows, and transformation rules to run API Promotion operations efficiently and safely.

## Environment Strategy

### Environment Separation with Instance Types

Choose the appropriate instance type for each environment. This provides both visual distinction and helps you apply the approval mechanism at the right level.

| Environment | Recommended Instance Type | Approval Required? |
| ----------- | ------------------------- | ------------------ |
| Development | Development               | No                 |
| Test        | Test                      | No or Optional     |
| Staging     | Staging                   | Yes                |
| Production  | Production                | Yes                |

<Tip>
  Activate the approval mechanism for all transfers to the Production environment. This prevents accidental transfers.
</Tip>

### Staged Transfer

Instead of transferring APIs directly from Development to Production, follow a staged approach:

```
Development → Test → Staging → Production
```

Verify that the transferred configuration works correctly at each stage before moving to the next environment.

## [Environment Variable](/en/concepts/core-concepts/environment-variable) Management

### Consistent Variable Naming

Use the same variable keys across all environments. Automatic mapping relies on exact key name matching.

**Correct approach:**

* Development: `BACKEND_URL = https://dev-api.example.com`
* Production: `BACKEND_URL = https://api.example.com`

**Incorrect approach:**

* Development: `DEV_BACKEND_URL = https://dev-api.example.com`
* Production: `PROD_BACKEND_URL = https://api.example.com`

### Missing Variable Check

Check for missing variables in the environment variable mapping step when creating a mapping. If there are missing variables in the target environment, define these variables in the target environment before the transfer.

<Warning>
  Missing environment variables can cause the transferred API to encounter errors at runtime in the target environment.
</Warning>

## Find & Replace Rules

### When to Use?

Use Find & Replace rules for values that are not managed with environment variables but differ between environments:

* Backend addresses (if environment variables are not used)
* Certificate references
* Timeout values
* Environment-specific configuration parameters

### JSONPath vs Plain Text

* **JSONPath**: Use to target a specific configuration field. More precise and safer
* **Plain text**: Use to change a text value across the entire API definition. Be careful of matches in unexpected places

<Tip>
  Prefer JSONPath expressions whenever possible. Plain text replacement can match in unexpected parts of the API definition.
</Tip>

## Pre-Flight Check

### Run Before Every Transfer

Pre-checks help you detect potential issues before the transfer. Specifically:

* Verifies that the target environment connection is active
* Checks for API version conflicts
* Detects authorization issues in advance

### Do Not Ignore Warnings

Items with **Warning** status in pre-check results do not block the transfer but indicate potential issues. It is recommended to evaluate these warnings and make necessary corrections.

## Approval Workflow

### Approver Selection

* Define at least two approvers for the Production environment
* Choose approvers from among those responsible for the target environment

### Notification Recipients

* Add people who need to be informed about execution status as notification recipients
* Configure email notifications especially for quick response to failed executions

## General Recommendations

<AccordionGroup>
  <Accordion title="Keep mappings up to date">
    When changes are made to the source API, refresh the mapping's comparison results to review the differences. This prevents unexpected changes from being transferred to the target environment.
  </Accordion>

  <Accordion title="Track execution history">
    Regularly check the statistics in the execution list. Investigate the causes of failed executions and eliminate recurring errors.
  </Accordion>

  <Accordion title="Configure excluded fields correctly">
    Exclude environment-specific fields (IDs, dates, user information). System defaults cover most cases, but if you have custom fields, add them as user-defined fields.
  </Accordion>

  <Accordion title="Be careful with Proxy Group transfers">
    Proxy Group transfers cover all proxies and dependencies within the group. Transfer time may be longer for large groups. Prefer to transfer in a single operation to maintain integrity rather than splitting groups.
  </Accordion>

  <Accordion title="Monitor connection health">
    Regularly check health statuses in the instance list. Transfers to an unhealthy instance will fail.
  </Accordion>
</AccordionGroup>