API v1.2: Update Data Separation and Migration Guide for old Codes

WP Software License has introduced API version 1.2 to improve response handling and provide better structured data for update operations. While API 1.1 is deprecated, we understand that installations still run older plugins/themes versions that depend on the legacy format. This guide explains the differences between versions and how to maintain backwards compatibility.

Key Differences Between API 1.1 and 1.2

API 1.1 (Deprecated)

In API 1.1, update data was embedded directly within the message field. When calling update-related endpoints like plugin_update, theme_update, plugin_information, or code_version, the entire response structure contained serialized update information within a single field.

API 1.2 (Current)

API 1.2 introduces a cleaner, more structured approach:

• Dedicated update_data field: All update details are now contained in a separate, clearly defined entry
• Clean message field: Contains human-readable text messages (e.g., “Plugin update check completed”) for logging and debugging purposes

Update Data Structure (API 1.2)

The update_data field in API 1.2 includes:

• new_version: The latest available version number (e.g., “1.4.6”)
• date: Release date in YYYY-MM-DD format (e.g., “2023-09-18”)
• package: Download URL with authentication parameters for secure retrieval
• upgrade_notice: User-facing information about the update
• author: Plugin/theme author name
• tested: WordPress version compatibility indicator
• homepage: Official product homepage URL
• icons: SVG or image assets for display purposes

Managing Backwards Compatibility

The primary challenge occurs when older plugin installations continue to expect the API 1.1 format. To solve this without requiring immediate updates across all installations, implement a response adapter, through a custom code, can be used.  Older plugins that expect the full update payload inside message will fail or ignore updates when talking to a v1.2 server.

The custom code should detect the requesting plugin version and adjust the response accordingly:

1. Version Detection: Check the API request for a version header or parameter indicating which format the caller expects
2. Conditional Response Formatting: If the request originates from API 1.1-compatible code, reformat the API 1.2 response to match the legacy structure
3. Transparent Migration: This approach allows old plugins to continue functioning while new versions benefit from the improved structure

The following code should be inserted within /wp-content/mu-plugins/woosl-custom.php  to ensure that when caching is active, the code is loaded:

    add_filter('WOOSL/API_call/response', '_woosl_api_response_convert_to_outdated_plugins', 10, 3);
    function _woosl_api_response_convert_to_outdated_plugins( $response, $args, $api_object )
        {
            //The plugin slug for which we check the API response
            $PluginSlug     =   'my_custom_plugin_slug';
            
            //The plugin version considered outdated, which will receive the response in the old API format.
            //If the call does not include a version, it will be considered an old plugin version
            $PluginOutdatedVersion  =   '1.2';
            
            
            
            
            If ( $args['product_unique_id'] !== $PluginSlug )
                return $response; 
            
            If ( ! empty ( $args['version'] ) &&  version_compare( $args['version'], $PluginOutdatedVersion, '>'))
                return $response;
            
            //check if the API call method is not activate
            $allowed_methods    =   array ( 
                                                'plugin_update',
                                                'theme_update',
                                                'plugin_information',
                                                'code_version',
                                                );
            if  ( ! in_array ( $args['woo_sl_action'], $allowed_methods) ) 
                return $response;
                
            if ( !is_array ( $response )    ||  count ( $response ) <   1 )
                return $response;
                
            foreach ( $response as  $key    =>  $response_block )
                {
                    if ( isset ( $response_block['update_data'] ) )
                        $response[ $key ]['message']    =   $response_block['update_data'];
                }
                  
                        
            return $response;
        }

In the code above, update $PluginSlug to match your plugin’s identifier and set $PluginOutdatedVersion to the highest version number still using the API 1.1 format. This ensures the adapter correctly routes legacy requests to the appropriate response structure.

This ensures that:

• New plugins receive clean, structured API 1.2 responses
• Legacy plugins continue to function without modification
• You maintain a single API endpoint serving both formats
• Plugin authors can migrate to the new format at their own pace