Versions and migration

ApiGo uses two different levels of "version" to describe API evolution:

Concept	Field	Granularity	Purpose
API version	version / sourceVersion	API definition	Business version number, such as v1 or v2
Release revision	deployRevision	Each release	Incrementing number for each release of the same version, used for rollback

An API version upgrade produces a new API source; a release revision is just one snapshot of the same API source. Do not conflate the two.

Version management

Viewing versions

In "API list → Released", click the version number in the "Version management" column to open the version management dialog.

dev environment shows all API sources in the version family:

Column	Description
API ID	API source ID
API name	Click to open API details
Authentication type	None / Simple / Signature
API status	Draft / online / offline
Version	API version
Revision	Current release revision
Released at	Last release/snapshot time
Actions	Edit, upgrade version, sync environment, take online/offline, delete

Non-dev environments show all release snapshots of the API in that environment, with actions for taking online/offline and deleting.

Version upgrade

Version upgrade is used to maintain multiple business versions in parallel (such as a stable v1 and a new v2):

1. Click "Version upgrade" in the dev version list;
2. The workbench opens the current API in upgrade mode;
3. Modify the API content and change "Version" to the new version number;
4. Saving creates a new API source with a draft, offline status;
5. Release the new version, then sync it to other environments as needed.

Upgrade rules:

• The version number must be a positive integer;
• Version numbers must be unique within a version family; otherwise the message "This API version already exists; choose a different version number" appears;
• The new version's API path and request method must not conflict with other versions (the platform validates by path + method);
• The new version shares the version family link (apiLinkId) with the original but has its own release snapshots and online/offline status;
• The original version is not replaced or taken offline and remains usable.

Upgrade or re-release

If you only change API content without changing the business version, just save and re-release. Use version upgrade only when the old version must keep serving traffic.

Deleting versions

Environment	Deletion behavior
dev	Deletes the API source and its related data; not allowed while an online snapshot still exists
Non-dev	Deletes all release snapshots of the API in that environment without affecting other environments

When deleting APIs in bulk, if any environment has an online snapshot, the whole batch is rejected.

Revisions and rollback

How revision numbers are generated

Each release that generates a dev snapshot increments the revision number within the version family. Syncing to a target environment reuses dev's revision number, so the same revision can have different snapshot IDs in different environments while sharing the same revision number, which simplifies reconciliation.

Rollback

Rollback applies only to non-dev environments:

1. Click "History versions" on the target environment row;
2. Select a non-current snapshot;
3. Click "Roll back" and confirm;
4. The system makes that snapshot current, marks the others as non-current and refreshes the runtime state.

Rollback requires the data source to still be accessible; dev does not support rollback, so release again instead.

Deleting snapshots

Deleting a non-dev version deletes all snapshots of the API in that environment, including historical revisions. The operation cannot be undone and does not affect dev or other environments.

Migration bundles

A migration bundle (.apigo.json) moves API definitions between projects, environments or deployment instances. It suits copying from a test environment to another project, delivering private deployments and backing up API configuration.

Export

Entry: API list → Released → Bulk export.

1. Select the source environment and keyword, then check the APIs to export (based on that environment's currently effective snapshots);
2. Choose the data items to include;
3. Click export; the browser downloads the migration bundle.

Option	Default	Description
API information	Always included	API definitions, parameters, proxy/orchestration configuration and plugin configuration
Data sources	Yes	Data source connection configuration (passwords and SecretKeys are exported as empty)
Groups and categories	Yes	Group tree and category definitions
Test cases	No	The APIs' dev test cases

Limits and notes:

• Up to 100 APIs can be exported per operation;
• Only the currently effective snapshots of the selected environment are exported;
• File name format: apigo-migration-{projectId}-{yyyyMMddHHmm}.apigo.json;
• The bundle uses ApiGo's own format and contains an OpenAPI 3.0.3 document;
• Project and environment prefixes are stripped from exported paths and re-applied on import;
• Data source passwords and SecretKeys are not written into the bundle; fill them in again or map them during import.

Import

Entry: API list → Released → Import APIs. The flow has three steps: "Upload → Preview → Import".

1. Upload

You can upload or paste .apigo.json / .json content. The platform validates:

• The content must be JSON;
• The bundle version must be 1.x;
• The embedded OpenAPI document must be 3.x.

2. Preview

The preview shows the total number of APIs, how many will be added, overwritten and skipped, plus the number of data sources and test cases. Each API can be adjusted individually:

Item	Description
API name	Can be renamed
API path	Can be changed
Handling	Add / overwrite / skip; existing APIs cannot be set to add
Target group	Select an existing group; if left empty, a group with the same name is created automatically

Data source handling:

• Create a new data source: Created from the definition in the bundle; the password must be entered (encrypted with SM2 on the frontend before transmission);
• Map to an existing data source: Selected from the current project's data source list;
• If the bundle contains no data sources, a default data source must be selected.

3. Import

Select the target environment and submit. The target environment must:

• Exist and be enabled;
• Not be the production environment (isProd = 1); imports into production are rejected;
• Allow importing into dev; imported APIs are in a "released, offline" state and must be taken online manually.

Import rules:

• Up to 100 APIs can be imported per operation;
• Duplicates are determined by "API path + request method";
• Overwriting updates existing API definitions but does not delete APIs in the target environment that are not in the bundle;
• Groups are resolved in this order: target group → group mapping → lookup by name → automatic creation → default group;
• API paths have the project prefix and environment prefix re-applied;
• The revision number is the current maximum revision + 1;
• Data sources are mapped by name, falling back to the default data source;
• If any write fails, the whole import rolls back and no partially imported data is left behind.

Production environment

Migration import must never write directly to the production environment. The correct approach is to import into dev or a staging environment, verify, and then release to production via "Sync environment".

FAQ

Symptom	Cause	Resolution
Saving a version upgrade fails	The version number is duplicated, or the path/method conflicts with an existing version	Use a different version number or API path
The old version disappears after an upgrade	Normal save was used instead of version upgrade	Version upgrade adds a new API source and does not overwrite the old version; check whether you edited the old version directly
The rollback button is grayed out	The selected snapshot is the current one, or you are in dev	Select a historical revision; in dev, release again
Export warns that more than 100 APIs are selected	Too many selected at once	Export in batches
Import warns about the production environment	The target environment is marked as production	Choose a non-production environment
Imported APIs cannot be called	The APIs are released but offline	Take them online in the target environment
Data source errors after import	The password/SecretKey was not entered or was mapped incorrectly	Edit the API and reselect the data source, or import again and complete the mapping
Part of the import failed	Any single failure rolls back the whole import	Locate and fix the issue based on the returned error, then retry

Related documentation

• API list
• Environments and releases
• API definition and lifecycle
• Quick start