Best Practices
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 |
Activate the approval mechanism for all transfers to the Production environment. This prevents accidental transfers.
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 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.
Missing environment variables can cause the transferred API to encounter errors at runtime in the target environment.
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
Prefer JSONPath expressions whenever possible. Plain text replacement can match in unexpected parts of the API definition.
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
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.
Track execution history
Regularly check the statistics in the execution list. Investigate the causes of failed executions and eliminate recurring errors.
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.
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.
Monitor connection health
Regularly check health statuses in the instance list. Transfers to an unhealthy instance will fail.