Migrating Apicurio Registry deployments

Procedure

1. Export all data from Apicurio Registry 2.6. The following command downloads registry-export.zip to your working directory:

   curl -X GET "http://old-registry.my-company.com/apis/registry/v2/admin/export" \
     -o registry-export.zip

   Copy to Clipboard Toggle word wrap

2. Import the archive into Apicurio Registry 3.x by posting it to the admin import endpoint:

   curl -X POST "http://new-registry.my-company.com/apis/registry/v3/admin/import" \
     -H "Content-Type: application/zip" \
     --data-binary @registry-export.zip

   Copy to Clipboard Toggle word wrap

3. Validate the migrated content. Compare artifact counts between the legacy and new deployments:

   curl "http://old-registry.my-company.com/apis/registry/v2/search/artifacts"

   Copy to Clipboard Toggle word wrap

   curl "http://new-registry.my-company.com/apis/registry/v3/search/artifacts"

   Copy to Clipboard Toggle word wrap

   Check that global rules were imported successfully:

   curl "http://new-registry.my-company.com/apis/registry/v3/admin/rules"

   Copy to Clipboard Toggle word wrap

Procedure

1. Update your client configuration to target the v3 REST API base path:

   String registryUrl = "https://new-registry.my-company.com/apis/registry/v3";
   RegistryClient client = RegistryClientFactory.create(registryUrl);

   Copy to Clipboard Toggle word wrap

   Automation that previously targeted /apis/registry/v2 continues to function, but new functionality is only exposed through the v3 API.

2. Refresh your client dependencies to the latest 3.x SDKs generated with Kiota. For Maven-based Java applications, use the new artifact identifier:

   <dependency>
       <groupId>io.apicurio</groupId>
       <artifactId>apicurio-registry-java-sdk</artifactId>
       <version>3.1.0.Final-redhat-00004</version>
   </dependency>

   Copy to Clipboard Toggle word wrap

   Install the TypeScript, Python, or Go SDKs through the respective package managers (npm install @apicurio/apicurio-registry-sdk, pip install apicurioregistrysdk, or go get github.com/apicurio/apicurio-registry/go-sdk).

3. Align your integration code with the reorganized endpoints:

   • Manage artifact metadata at /groups/{groupId}/artifacts/{artifactId}.
   • Retrieve or create content exclusively through /versions endpoints.
   • Replace calls to /test endpoints with the dryRun query parameter.
   • Use /search/groups and /search/versions where you previously enumerated artifacts indirectly.
4. Adopt the branch API if you need parallel development streams. Branches allow you to promote or merge versions without duplicating artifacts.
5. If you build Kafka SerDes integrations, verify that serializers and deserializers still reference the correct registry URL and consider enabling group- or artifact-level rules introduced in 3.x to enforce compatibility upstream.