UPGRADE-API-1.13.md

UPGRADE FROM v1.13.6 TO v1.13.7

1. The default order attribute has been added to the endpoint GET /admin/customers endpoint

   +   <attribute name="order">
   +       <attribute name="createdAt">DESC</attribute>
   +   </attribute>

UPGRADE FROM v1.13.3 TO v1.13.4

1. The api/v2/shop/adjustments/{id} endpoint has been disabled.

UPGRADE FROM v1.12.x TO v1.13.0

ApiBundle is no longer experimental and is now following the same support policy as the rest of Sylius.

Classes and services changes

1. The following Command constructor signatures have changed:

   Sylius\Bundle\ApiBundle\Command\Account\ChangeShopUserPassword:

       public function __construct(
   -       public ?string $newPassword, 
   +       public string $newPassword, 
   -       public ?string $confirmNewPassword,
   +       public string $confirmNewPassword,
   -       public ?string $currentPassword,
   +       public string $currentPassword,
       )

   Sylius\Bundle\ApiBundle\Command\Catalog\AddProductReview:

       public function __construct(
   -       public ?string $title,
   +       public string $title,
   -       public ?int $rating,
   +       public int $rating,
   -       public ?string $comment,
   +       public string $comment,
           public string $productCode,
           public ?string $email = null,
       )

   Sylius\Bundle\ApiBundle\Command\Account\ResetPassword

   public function __construct(
   -      public string $resetPasswordToken,
   +      public string $token,
          public ?string $newPassword = null,
          public ?string $confirmNewPassword = null,
   )

   Sylius\Bundle\ApiBundle\Command\Account\VerifyCustomerAccount:

       public function __construct(
   -       public $token,
   +       public string $token,
   +       public ?string $channelCode = null,
   +       public ?string $localeCode = null,
       )
   

2. The following Command Handlers constructor signatures have changed:

   Sylius\Bundle\ApiBundle\CommandHandler\Account\SendAccountRegistrationEmailHandler:

   use Sylius\Bundle\CoreBundle\Mailer\AccountRegistrationEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
           private UserRepositoryInterface $shopUserRepository,
           private ChannelRepositoryInterface $channelRepository,
   -       private SenderInterface $emailSender,
   +       private AccountRegistrationEmailManagerInterface $accountRegistrationEmailManager,
       )

   Sylius\Bundle\ApiBundle\CommandHandler\Account\SendAccountVerificationEmailHandler:

   use Sylius\Bundle\CoreBundle\Mailer\AccountVerificationEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
           private UserRepositoryInterface $shopUserRepository,
           private ChannelRepositoryInterface $channelRepository,
   -       private SenderInterface $emailSender,
   +       private AccountVerificationEmailManagerInterface $accountVerificationEmailManager,
       )

   Sylius\Bundle\ApiBundle\CommandHandler\Account\SendResetPasswordEmailHandler:

   use Sylius\Bundle\CoreBundle\Mailer\ResetPasswordEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
   -       private SenderInterface $emailSender,
           private UserRepositoryInterface $shopUserRepository,
           private ChannelRepositoryInterface $channelRepository,
   +       private ResetPasswordEmailManagerInterface $resetPasswordEmailManager,
       )

   Sylius\Bundle\ApiBundle\CommandHandler\Checkout\SendOrderConfirmationHandler:

   use Sylius\Bundle\CoreBundle\Mailer\OrderEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
   -       private SenderInterface $emailSender,
           private OrderRepositoryInterface $orderRepository,
   +       private OrderEmailManagerInterface $orderEmailManager,
       )

   Sylius\Bundle\ApiBundle\CommandHandler\Checkout\SendShipmentConfirmationEmailHandler:

   use Sylius\Bundle\CoreBundle\Mailer\ShipmentEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
   -       private SenderInterface $emailSender,
           private ShipmentRepositoryInterface $shipmentRepository,
   +       private ShipmentEmailManagerInterface $shipmentEmailManager,
       )

   Sylius\Bundle\ApiBundle\CommandHandler\SendContactRequestHandler:

   use Sylius\Bundle\CoreBundle\Mailer\ContactEmailManagerInterface;
   use Sylius\Component\Mailer\Sender\SenderInterface;
   
       public function __construct(
   -       private SenderInterface $emailSender,
           private ChannelRepositoryInterface $channelRepository,
   +       private ContactEmailManagerInterface $contactEmailManager,
       )

3. The constructor signature of Sylius\Bundle\ApiBundle\Serializer\ChannelDenormalizer has been changed:

   use Sylius\Component\Resource\Factory\FactoryInterface;
   
       public function __construct(
           private FactoryInterface $channelPriceHistoryConfigFactory,
   +       private FactoryInterface $shopBillingDataFactory
       )

4. The constructor signature of Sylius\Bundle\ApiBundle\EventSubscriber\TaxonDeletionEventSubscriber has been changed:

   use Sylius\Component\Core\Promotion\Checker\TaxonInPromotionRuleCheckerInterface;
   
       public function __construct(
           private ChannelRepositoryInterface $channelRepository,
   +       private TaxonInPromotionRuleCheckerInterface $taxonInPromotionRuleChecker,
       )

5. The Sylius\Bundle\ApiBundle\ApiPlatform\Bridge\Symfony\Bundle\Action\SwaggerUiAction controller has been removed. Therefore, the api_platform.swagger.action.ui service ID points to the API Platform's SwaggerUiAction controller.

6. The following services have been removed:

   • Sylius\Bundle\ApiBundle\Swagger\AdminAuthenticationTokenDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ShopAuthenticationTokenDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ProductDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ProductImageDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ProductSlugDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ProductVariantDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\ShippingMethodDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\PathHiderDocumentationNormalizer
   • Sylius\Bundle\ApiBundle\Swagger\AcceptLanguageHeaderDocumentationNormalizer

   Responsibility of these services has been moved to the corresponding services tagged with sylius.open_api.modifier:

   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\AdminAuthenticationTokenDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ShopAuthenticationTokenDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ProductDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ProductImageDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ProductSlugDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ProductVariantDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ShippingMethodDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\PathHiderDocumentationModifier
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\AcceptLanguageHeaderDocumentationModifier

7. All usages of ApiPlatform\Core\Api\IriConverterInterface have been switched to its non-deprecated counterpart ApiPlatform\Api\IriConverterInterface. Due to that, the constructor and usage in the following classes have been changed accordingly:

   • Sylius\Bundle\ApiBundle\Controller\GetProductBySlugAction
   • Sylius\Bundle\ApiBundle\Controller\UploadAvatarImageAction
   • Sylius\Bundle\ApiBundle\EventListener\AdminAuthenticationSuccessListener
   • Sylius\Bundle\ApiBundle\EventListener\AuthenticationSuccessListener
   • Sylius\Bundle\ApiBundle\Filter\Doctrine\CatalogPromotionChannelFilter
   • Sylius\Bundle\ApiBundle\Filter\Doctrine\ProductVariantCatalogPromotionFilter
   • Sylius\Bundle\ApiBundle\Filter\Doctrine\ProductVariantOptionValueFilter
   • Sylius\Bundle\ApiBundle\Filter\Doctrine\ProductVariantOptionValueFilter
   • Sylius\Bundle\ApiBundle\Filter\Doctrine\TaxonFilter
   • Sylius\Bundle\ApiBundle\Serializer\ChannelPriceHistoryConfigDenormalizer
   • Sylius\Bundle\ApiBundle\Serializer\ProductNormalizer
   • Sylius\Bundle\ApiBundle\Serializer\ProductVariantNormalizer
   • Sylius\Bundle\ApiBundle\Serializer\ZoneDenormalizer

8. The Sylius\Bundle\ApiBundle\Filter\Doctrine\CatalogPromotionChannelFilter service and class has been renamed to Sylius\Bundle\ApiBundle\Filter\Doctrine\ChannelsAwareChannelFilter.

Resources changes

1. The following endpoints short names have been changed:

   • AdminResetPasswordRequest -> Administrator
   • AccountResetPasswordRequest -> Customer
   • ShopUserToken -> Customer and Security
   • AdminUserToken -> Administrator and Security
   • ContactRequest -> Contact
   • VerifyCustomerAccount -> Customer

2. The item operation path for ProductVariantTranslation resource has been changed:

   • GET /admin/product-variant-translation/{id} -> GET /admin/product-variant-translations/{id}

3. The following shop endpoints for getting the translation resources have been removed:

   • GET /shop/taxon-translations/{id}
   • GET /shop/product-translations/{id}
   • GET /shop/product-variant-translations/{id}
   • GET /shop/shipping-method-translations/{id}

   The fields those endpoint were exposing are available on their respective translation subject resources.

4. The following endpoints regarding authentication tokens have been changed:

   • POST /admin/authentication-tokens -> POST /admin/administrators/token
   • POST /shop/authentication-tokens -> POST /shop/customers/token

5. The following endpoints regarding password reset have been changed:

   • POST /admin/reset-password-requests -> POST /admin/administrators/reset-password
   • PATCH /admin/reset-password-requests/{resetPasswordToken} -> PATCH /admin/administrators/reset-password/{token}
   • POST /shop/reset-password-requests -> POST /shop/customers/reset-password
   • PATCH /shop/reset-password-requests/{resetPasswordToken} -> PATCH /shop/customers/reset-password/{token}

6. The following endpoints regarding customer account verification have been changed:

   • POST /shop/account-verification-requests -> POST /shop/customers/verify
   • PATCH /shop/account-verification-requests/{token} -> PATCH /shop/customers/verify/{token}

7. The following endpoints regarding contact requests have been changed:

   • POST /shop/contact-requests -> POST /shop/contact

8. Update in Translations Handling

   The process for creating or updating translations via the API has been refined. Now, the locale for each translation is determined directly from its key, making the explicit transmission of the locale field redundant. Although the API continues to support the explicit sending of the locale field but in cases of a mismatch between the key and an explicitly sent locale, the API will respond with the Sylius\Bundle\ApiBundle\Exception\TranslationLocaleMismatchException.

9. Product and taxon editing at /admin/product-taxons/{id} operation has been disabled to improve data integrity. To modify a product-taxon relationship remove the existing one and create a new one.

10. The keys for adjustment endpoints' responses have been changed:

    {
      ...
    - "order_item": "string",
    + "orderItem": "string",
    - "order_item_unit": "string",
    + "orderItemUnit": "string",
      ...
    }

11. The customer key has been removed from admin address endpoints' responses.

12. The status key has been removed from shop product review endpoints' responses.

13. The author key has been changed in shop product review endpoints' responses:

    {
      ...
    - "author": "string(IRI)",
    + "author": {
    +   "@id": "string(IRI)",
    +   "@type": "string",
    +   "firstName": "string",
    + },
    }

14. Resolving the path property of every resource implementing Sylius\Component\Core\Model\ImageInterface has been changed to always rely on filters. The default filter has been set to sylius_original, but can be changed via configuration:

    sylius_api:
        default_image_filter: custom_filter

    Due to this change the previously used configuration node product_image_prefix and its corresponding parameter sylius_api.product_image_prefix have been removed.

Miscellaneous

1. All the :read serialization groups are now split to index and show. The :read serialization groups are now considered deprecated and will no longer be used in the future. There is a BC layer that will allow you to use the :read serialization group Sylius\Bundle\ApiBundle\SerializerContextBuilder\ReadOperationContextBuilder by adding the read serialization group to your context. To configure skipping adding the index and show or read serialization groups to the context, add the following configuration to your config/packages/_sylius.yaml file:

   sylius_api:
       serialization_groups:
           skip_adding_index_and_show_groups: true
           skip_adding_read_group: true

2. All Sylius serialization groups have been prefixed with sylius:. If you extend any Sylius resources, you should update your serialization groups to use the new prefix. Non-prefix serialization groups are considered deprecated and will be removed in Sylius 2.0.

3. Typo in the constraint validator's alias returned by Sylius\Bundle\ApiBundle\Validator\Constraints\ChangedItemQuantityInCart::validatedBy has been fixed. Previously it was sylius_api_validator_changed_item_guantity_in_cart and now it is sylius_api_validator_changed_item_quantity_in_cart.

4. The sylius.api.product_taxon_filter filter has been removed and its functionality has been superseded by the sylius.api.search_filter.taxon.code filter. The usage stays the same.

5. Due to changes with images' path property resolving the following services have been changed to make their context broader:

   • Sylius\Bundle\ApiBundle\Serializer\ProductImageNormalizer -> Sylius\Bundle\ApiBundle\Serializer\ImageNormalizer
   • Sylius\Bundle\ApiBundle\OpenApi\Documentation\ProductImageDocumentationModifier -> Sylius\Bundle\ApiBundle\OpenApi\Documentation\ImageDocumentationModifier
   • Sylius\Bundle\ApiBundle\Provider\ProductImageFilterProviderInterface -> Sylius\Bundle\ApiBundle\Provider\ImageFiltersProviderInterface
   • Sylius\Bundle\ApiBundle\Provider\LiipProductImageFilterProvider -> Sylius\Bundle\ApiBundle\Provider\LiipImageFiltersProvider