This article outlines migration package operations using GraphStudio’s APIs, including details on request structure, endpoint usage, URL encoding, and error handling. The APIs allow us to automate common tasks such as importing and exporting migration packages.
Overview
- Export a Migration Package
- Prepare Migration Package for Import
- Import a Migration Package
1. Export a Migration Package
To export an existing migration package from the current GraphStudio environment, use the POST/migration/{migration_package_uri}/export endpoint.
- API:
POST https://<hostname>/migration/{migration_package_uri}/export
This package contains datasets, ontologies, graphmart configurations, and other related resources. The required parameter is migration_package_uri.
For a full list of the endpoint’s configurations, refer to the documentation:
https://docs.cambridgesemantics.com/anzo/v5.4/api/#/migration/ExportMigrationPackage
Example Request
POST https://<hostname>/migration/movies-v1/export
Once the export is complete, you can download it via:
GET https://<hostname>/api/migration-packages/<package-id>/download
The export request returns a binary response, which can then be saved as a ZIP file.
2. Prepare Migration Package for Import
Before importing a migration package, ensure that:
- The migration package is saved as a valid
.zip file. - Any environment-specific settings (e.g., dataset paths, connection strings) are updated if necessary.
- You have the required permissions in the target environment.
3. Import a Migration Package
Assuming the migration package is ready to be imported, we can use the POST/migration/import endpoint to bring the migration package into the target GraphStudio environment. You can choose whether to immediately apply it as the current state or just store it as a version.
- API:
POST https://<hostname>/migration/import
The only query parameter is force which, if set to true, imports graphs with sufficient permissions even if some graphs are missing permissions.
The only required request body parameter is migrationPackage which is the .zip migration package file, but parameters like applyImport can help us specify whether to apply to the current environment immediately or to just create a version. For a full list of configurations, refer to:
https://docs.cambridgesemantics.com/anzo/v5.4/api/#/migration/importMigrationPackage
4. Tools and Automation
Once you are comfortable creating migration packages manually via the API, the next step is to integrate these calls into automated workflows. Automating migration package creation ensures consistency, repeatability, and easier promotion of resources across environments (eg. development, testing, production).
Postman is helpful for interactively building and testing migration package creation requests. You can save these requests in a collection and run them on demand. With Newman CLI, these requests can be scheduled or embedded into simple batch jobs, making migrations reproducible without additional coding.
- Python (and other scripting languages)
With Python’s requests library (or similar), you can build migration automation scripts that:
- Create migration packages programmatically
- Tag versions with labels and comments
- Export and store packages in your organization’s artifact repositories
- Trigger imports into new environments
This scripting approach ensures migrations are repeatable and version-controlled, reducing the chance of manual errors.
- Orchestration and Enterprise Integration
Migration package creation is often tied to environment management and release pipelines. GraphStudio’s APIs fit neatly into the tools enterprises already use:
- Jenkins – Incorporate package creation into CI/CD pipelines, ensuring that migration packages are always generated and deployed as part of release cycles.
- Airflow – Automate package creation alongside ETL processes so that migrations are ready when data or models change.
- Kafka / Event Streams – Trigger migration package creation when new datasets or configurations are available, ensuring environments remain synchronized.
- Custom Automation Systems – Since the APIs are standard HTTP calls, they can be integrated into any job runner or scheduler your organization relies on.
Since migration packages are exposed as API resources, they can be created, exported, and imported automatically using whatever orchestration framework your organization already uses. This allows migrations to move from a manual, ad-hoc process to a fully automated, governed workflow, making cross-environment management more reliable and scalable.
5. Troubleshooting and Debugging
- 401 Unauthorized: Verify your access token is valid.
- 403 Forbidden: Check if you have
Migration Package Import permissions. - Partial Import: Review
detail in the API response to see which graphs were skipped. - Corrupt Package: Ensure the
.zip is valid and not modified incorrectly.
References
