Explore Admin API v4 features and changes
Prerequisites
Before proceeding with the upgrade, ensure that the following prerequisites are met.- Notice to and approval by Voyado have been provided for the upgrade.
- There is a currently live integration in production using Admin API v3 for imports.
- Every unique product group, product, variant, and content key serves as a consistent identifier for the same item across different markets. That is, a single identifier must not be used for different products in two markets.
- Market identifiers and locales are kept identical to the ones used for v3 during the upgrade process.
Rollback and recovery
It is possible to downgrade to Admin v3 at any point during the upgrade process. When doing so, all v4 import endpoints will start returning405 response code errors, and all v3 import endpoints will start working as previously.
To downgrade to v3, perform a full v3 import admin/v3/import/data with the query parameter downgrade=true.
Upgrade process
There are two approaches to upgrading the data feed: one basic and one slightly more advanced. The one most suitable for you depends on the number of import sources and your import uptime requirements. The main difference is that the advanced upgrade will have a fully uninterrupted partial import flow during the upgrade process. The overview of the processes explains the main components of the upgrade process, and the step-by-step sections provide an example of how to roll it out safely, including the usage of a test environment and some utility features provided by Voyado. Depending on how fast rollouts are made and what levels of precautions are needed for your setup, not all steps are needed as long as the tasks in the overview are fulfilled.- No v4 configuration imports should be made during the upgrade process.
- For other Admin endpoints than those for the data feed, update the version in the request path.
Basic data feed upgrade
When
If only full imports are made, or all imports are made from a single system, or if temporary halts in the partial update flow are acceptable during the import process, the basic upgrade flow is recommended.Overview
The basic upgrade process fundamentally consists of these tasks:1
Migrate full imports
Migrate the v3 full import to the v4 catalog format for replacing the catalog and ensure it is imported successfully.
2
Migrate partial imports
Migrate all v3 partial and attribute modification imports to the v4 catalog format for updating the catalog and ensure they are imported successfully.
3
Schedule only v4 updates
Ensure the scheduling of future updates uses v4 and that v3 updates are turned off.
Step by step
The following steps are recommended to be performed in your test environment, before rolling out or making the equivalent changes to production.1
Export v3 data (optional)
Make a full Admin v3 export
admin/v3/export/data for immediate access in case of a need to roll back.2
Export a catalog draft (optional)
Use the new endpoint
admin/v4/export/upgrade-catalog to get an example of how your data roughly should look in the new format for reference.3
Validate the catalog draft (optional)
Import the retrieved file to the new endpoint
admin/v4/import/catalog via PUT, and with the query parameter validationOnly=true.4
Resolve draft validation errors (optional)
Should you get an error response, see troubleshooting and ensure these errors are resolved in the file you are to generate in step 6.
5
Update import retry handling
Modify any automated import retries on import errors to handle
405 response code errors. On 405, do not retry the import.6
Generate a catalog replacement import
Generate an import for replacing the catalog according to the catalog specification and following the guidelines. The result from this should normally be similar to what you retrieved from step 2.
7
Import the catalog
Import the generated file to the new endpoint
admin/v4/import/catalog via PUT. The cluster will now no longer accept v3 data imports.8
Resolve catalog import errors
Should you get an error response, see troubleshooting and ensure these errors are resolved. Repeat this and the previous step until the file is imported successfully.
9
Validate site behavior
Validate that the site connected to the cluster behaves as before. No alterations to the Storefront API usage should be necessary.
10
Generate partial update imports
For partial updates, generate import files for updating the catalog according to the catalog specification and following the guidelines.
11
Import a partial update
Import a file produced from the previous step to the new endpoint
admin/v4/import/catalog via POST.12
Resolve partial update errors
Should you get an error response, see troubleshooting and ensure these errors are resolved. Repeat this and the previous step until the file is imported successfully.
13
Update scheduled imports
Update the code that schedules full imports and partial imports to only use v4 imports.
14
Complete the upgrade
The upgrade is done.
Advanced data feed upgrade
When
The advanced upgrade process is recommended when there are multiple import sources and either of the following conditions are true:- It is paramount that there are no interruptions of partial or modification imports during the upgrade process.
- Rolling out releases to your import systems is very time-consuming.
Overview
In the advanced upgrade process, your data sources will produce both v3 and v4 import formats simultaneously during a period of time, with some of the requests failing. It also differs from the basic flow in that sources for partial updates are rolled out prior to full imports, and that the steps for the test environment and production environment differ slightly. The advanced upgrade process fundamentally consists of these tasks:1
Test environment: migrate full imports
Migrate the v3 full import to the v4 catalog format for replacing the catalog and ensure it is imported successfully.
2
Test environment: migrate partial imports
Migrate all v3 partial and attribute modification imports to the v4 catalog format for updating the catalog and ensure they are imported successfully.
3
Production environment: release dual-version partial imports
Release all partial and attribute modification sources to produce imports of both v3 and v4 imports. Note: all v4 imports will fail until step 4 is completed.
4
Production environment: release full imports
Release the import source for full imports. The first can be pushed manually if imports are infrequent. Note: all v3 imports will now fail.
5
Schedule only v4 updates
Ensure the scheduling of future updates only uses v4 and that v3 updates are turned off.
Step by step
1
Test environment: validate the basic upgrade
Perform steps 1-12 from the basic data feed upgrade.
2
Test environment: add v4 partial imports
Update all import systems that produce partial imports or attribute modifications to also produce v4 imports.
3
Production environment: deploy v4 partial imports
Roll out the changes to the import systems that produce partial imports or attribute modifications. Note: all v4 imports will fail on production until later in the upgrade process — this is expected.
4
Test environment: add v4 full imports
Update the import systems that produce full updates to also produce v4 imports.
5
Production environment: deploy v4 full imports
Roll out the changes to the import system that produces full imports.
6
Production environment: wait for the first v4 import
Wait until the first v4 import has occurred. If full imports are infrequent, optionally trigger a v4 catalog replacement import manually. Note that all v3 imports will now start to fail on production while all v4 imports should succeed — this is expected.
7
Test environment: remove v3 imports
Remove v3 imports from all import source systems.
8
Production environment: remove v3 imports
Roll out removal of v3 imports to all import source systems.
9
Complete the upgrade
The upgrade is done.