Skip to content

UPGRADE-API-2.0.md

Latest commit

 

History

History
497 lines (432 loc) · 25 KB

UPGRADE-API-2.0.md

File metadata and controls

497 lines (432 loc) · 25 KB

UPGRADE FROM 1.14 TO 2.0

Codebase

  • The following classes were removed:

    • Sylius\Bundle\ApiBundle\EventListener\PostgreSQLDriverExceptionListener

  • The following services were removed:

    • sylius.listener.api_postgresql_driver_exception_listener

  • Non-prefix serialization groups in Sylius resources have been removed. If you have extended any of them, you must prefix them with sylius:, for example:

    - #[Groups(['admin:product:index'])]
+ #[Groups(['sylius:admin:product:index'])]

  • API Platform has dropped DataProviders and DataPersisters in favor of Providers and Processors, respectively. Due to this change, Sylius custom DataProviders and DataPersisters have been adapted to the new API Platform interfaces and their namespaced have been changed to StateProvider and StateProcessor respectively:

  • Sylius\Bundle\ApiBundle\DataPersister\*DataPersister => Sylius\Bundle\ApiBundle\StateProcessor\*Processor
  • Sylius\Bundle\ApiBundle\DataProvider\*DataProvider => Sylius\Bundle\ApiBundle\StateProvider\*Provider
  • API Platform has also dropped DataTransformers in favor of which some of them have been refactored into SerializerContextBuilders as follows:
  • Sylius\Bundle\ApiBundle\DataTransformer\ChannelCodeAwareInputCommandDataTransformer => Sylius\Bundle\ApiBundle\SerializerContextBuilder\ChannelCodeAwareContextBuilder
  • Sylius\Bundle\ApiBundle\DataTransformer\LocaleCodeAwareInputCommandDataTransformer => Sylius\Bundle\ApiBundle\SerializerContextBuilder\LocaleCodeAwareContextBuilder
  • Sylius\Bundle\ApiBundle\DataTransformer\LoggedInCustomerEmailIfNotSetAwareCommandDataTransformer => Sylius\Bundle\ApiBundle\SerializerContextBuilder\LoggedInCustomerEmailIfNotSetAwareContextBuilder
  • Sylius\Bundle\ApiBundle\DataTransformer\LoggedInShopUserIdAwareCommandDataTransformer => Sylius\Bundle\ApiBundle\SerializerContextBuilder\ChannelCodeAwareContextBuilder
  • The constructor of Sylius\Bundle\ApiBundle\Command\Account\RegisterShopUser has been changed:
    public function __construct(
    -   public string $firstName,
    -   public string $lastName,
    -   public string $email,
    -   public string $password,
    -   public bool $subscribedToNewsletter = false,
    +   protected string $firstName,
    +   protected string $lastName,
    +   protected string $email,
    +   protected string $password,
    +   protected ?string $channelCode,
    +   protected ?string $localeCode,
    +   protected bool $subscribedToNewsletter = false,
    ) {
    }
  • The constructor of Sylius\Bundle\ApiBundle\Command\Account\RequestResetPasswordToken has been changed:
    public function __construct(
    -   public string $email,
    +   protected string $email,
    +   protected ?string $channelCode,
    +   protected ?string $localeCode,
    ) {
    }
  • The constructor of Sylius\Bundle\ApiBundle\Command\SendContactRequest has been changed:
    public function __construct(
    -   private ?string $email = null,
    -   private ?string $message = null,
    +   protected ?string $channelCode,
    +   protected ?string $localeCode,
    +   protected ?string $email = null,
    +   protected ?string $message = null,
    ) {
    }
  • The constructor of Sylius\Bundle\ApiBundle\Command\Account\VerifyShopUser has been changed:
    public function __construct(
    -   public string $token,
    -   private ?string $localeCode = null,
    -   private ?string $channelCode = null,
    +   protected string $token,
    +   protected string $channelCode,
    +   protected string $localeCode,
    ) {
    }
  • The constructor of Sylius\Bundle\ApiBundle\Command\Account\ChangeShopUserPassword has been changed:
    public function __construct(
    -   public ?string $newPassword,
    -   public ?string $confirmNewPassword,
    -   public ?string $currentPassword,
    +   protected mixed $shopUserId,
    +   protected string $newPassword,
    +   protected string $confirmNewPassword,
    +   protected string $currentPassword,
    ) {
    }
  • The constructor of Sylius\Bundle\ApiBundle\Command\Account\RequestShopUserVerification has been created:
    public function __construct(
    +   protected string|int|null $shopUserId,
    +   protected ?string $channelCode,
    +   protected ?string $localeCode,
    ) {
    }

All the setter methods have been removed from the commands above and also there are some new getter methods accordingly to arguments visibility changes.

  • The parameter type and order of the Sylius\Bundle\ApiBundle\Controller\UploadAvatarImageAction::__construct has been changed:
    public function __construct(
        private FactoryInterface $avatarImageFactory,
        private AvatarImageRepositoryInterface $avatarImageRepository,
    -   private ImageUploaderInterface $imageUploader,
    -   private IriConverterInterface $iriConverter,
    +   private RepositoryInterface $adminUserRepository,
    +   private ImageUploaderInterface $imageUploader,
    )

  • The getCurrentPrefix method has been removed from the Sylius\Bundle\ApiBundle\Provider\PathPrefixProviderInterface.

  • The Sylius\Bundle\ApiBundle\Provider\PathPrefixProvider constructor has been changed due to refactor. Now, we provide the list of possible prefixes that we check in this service. This list can be set under the parameter: sylius.api_path_prefixes.

        public function __construct(
-       private UserContextInterface $userContext,
        private string $apiRoute,
+       private array $pathPrefixes,
    ) {
        ...
    }

  • The signature of method applyToCollection of the following classes has been changed:

    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AcceptedProductReviewsExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AddressesExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AvailableProductAssociationsInProductCollectionExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\CountryCollectionExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\CurrencyCollectionExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\EnabledProductVariantsExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\HideArchivedShippingMethodExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\LocaleCollectionExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\OrdersByChannelExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\OrdersByLoggedInUserExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsByChannelAndLocaleCodeExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsByTaxonExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsWithEnableFlagExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsWithEnableFlagExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\RestrictingFilterEagerLoadingExtension
    • Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\TaxonCollectionExtension
    public function applyToCollection(
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
    -   string $operationName = null,
    +   \ApiPlatform\Metadata\Operation $operation = null,
        array $context = [],
    ): void;

  • The Sylius\Bundle\ApiBundle\OpenApi\Documentation\PathHiderDocumentationModifier class and service have been removed. The sylius.api.paths_to_hide parameter used in this class has also been removed. We recommend defining endpoints with the ApiPlatform\Metadata\NotExposed class to hide specific operations.

  • The following parameters have been renamed:

    Old parameter New parameter
    sylius.security.new_api_route sylius.security.api_route
    sylius.security.new_api_regex sylius.security.api_regex
    sylius.security.new_api_admin_route sylius.security.api_admin_route
    sylius.security.new_api_admin_regex sylius.security.api_admin_regex
    sylius.security.new_api_shop_route sylius.security.api_shop_route
    sylius.security.new_api_shop_regex sylius.security.api_shop_regex
    sylius.security.new_api_user_account_route sylius.security.api_shop_account_route
    sylius.security.new_api_user_account_regex sylius.security.api_shop_account_regex

  1. The following configuration parameters have been removed:

    • sylius_api.legacy_error_handling
    • sylius_api.serialization_groups.skip_adding_read_group
    • sylius_api.serialization_groups.skip_adding_index_and_show_groups

Resource configuration changes

Updated API Routes

Resource Original Route Updated Route
AvatarImage GET - /api/v2/admin/avatar-images/{id} GET - /api/v2/admin/administrators/{id}/avatar-image
POST - /api/v2/admin/avatar-images POST - /api/v2/admin/administrators/{id}/avatar-image
DELETE - /api/v2/admin/avatar-images/{id} DELETE - /api/v2/admin/administrators/{id}/avatar-image
ShopUser, CustomerPassword, CustomerVerification POST - /api/v2/shop/reset-password-requests POST - /api/v2/shop/reset-password
PATCH - /api/v2/shop/reset-password-requests/{resetPasswordToken} PATCH - /api/v2/shop/reset-password/{resetPasswordToken}
POST - /api/v2/shop/account-verification-requests POST - /api/v2/shop/verify-shop-user
PATCH - /api/v2/shop/account-verification-requests/{token} PATCH - /api/v2/shop/verify-shop-user/{token}
AdminUserPassword POST - /api/v2/admin/reset-password-requests POST - /api/v2/admin/reset-password
PATCH - /api/v2/admin/reset-password-requests/{resetPasswordToken} PATCH - /api/v2/admin/reset-password/{resetPasswordToken}
CatalogPromotion GET - /api/v2/admin/catalog-promotion-actions/{id} GET - /api/v2/admin/catalog-promotions/{code}/actions/{id}
GET - /api/v2/admin/catalog-promotion-scopes/{id} GET - /api/v2/admin/catalog-promotions/{code}/scopes/{id}
Translation GET - /api/v2/admin/[resource]-translations/{id} GET - /api/v2/admin/[resource]/{code}/translations/{localeCode}
ChannelPricing GET - /api/v2/admin/channel-pricings/{id} GET - /api/v2/admin/product-variants/{code}/pricing/{id}
Order GET - /api/v2/admin/order-items/{id} GET - /api/v2/admin/orders/{orderToken}/items/{id}
Payment GET - /api/v2/shop/payments/{id} GET - /api/v2/shop/orders/{orderToken}/payments/{id}
Product GET - /api/v2/admin/product-images/{id} GET - /api/v2/admin/products/{code}/images/{id}
GET - /api/v2/admin/products-images GET - /api/v2/admin/products/{code}/images
GET - /api/v2/shop/product-images/{id} GET - /api/v2/shop/products/{code}/images/{id}
GET - /api/v2/admin/product-option-values/{code} GET - /api/v2/admin/product-options/{optionCode}/values/{code}
GET - /api/v2/shop/product-option-values/{code} GET - /api/v2/shop/product-options/{optionCode}/values/{code}
Promotion GET - /api/v2/admin/promotion-actions/{id} GET - /api/v2/admin/promotions/{code}/actions/{id}
GET - /api/v2/admin/promotion-coupons/{id} GET - /api/v2/admin/promotions/{code}/coupons/{id}
POST - /api/v2/admin/promotion-coupons/generate POST - /api/v2/admin/promotions/{promotionCode}/coupons/generate
PUT - /api/v2/admin/promotion-coupons/{code} PUT - /api/v2/admin/promotions/{promotionCode}/coupons/{couponCode}
DELETE - /api/v2/admin/promotion-coupons/{code} DELETE - /api/v2/admin/promotions/{promotionCode}/coupons/{couponCode}
GET - /api/v2/admin/promotion-rules/{id} GET - /api/v2/admin/promotions/{code}/rules/{id}
Provinces GET - /api/v2/admin/provinces/{code} GET - /api/v2/admin/countries/{countryCode}/provinces/{provinceCode}
PUT - /api/v2/admin/provinces/{code} PUT - /api/v2/admin/countries/{countryCode}/provinces/{provinceCode}
GET - /api/v2/shop/provinces/{code} GET - /api/v2/shop/countries/{countryCode}/provinces/{provinceCode}
Shipment GET - /api/v2/shop/shipments/{id} GET - /api/v2/shop/orders/{orderToken}/shipments/{id}
Taxon GET - /api/v2/admin/taxon-images/{id} GET - /api/v2/admin/taxons/{code}/images/{id}
POST - /api/v2/admin/taxon-images POST - /api/v2//admin/taxons/{code}/images
PUT - /api/v2/admin/taxon-images/{id} PUT - /api/v2/admin/taxons/{code}/images/{id}
DELETE - /api/v2/admin/taxon-images/{id} DELETE - /api/v2/admin/taxons/{code}/images/{id}
GET - /api/v2/shop/taxon-images/{id} GET - /api/v2/shop/taxons/{code}/images/{id}

Other Resource Changes

  1. CustomerVerification

    • The Sylius\Bundle\ApiBundle\Command\Account\VerifyCustomerAccount command has been renamed to Sylius\Bundle\ApiBundle\Command\Account\VerifyShopUser.
    • The Sylius\Bundle\ApiBundle\Command\Account\ResendVerificationEmail command has been renamed to Sylius\Bundle\ApiBundle\Command\Account\RequestShopUserVerification.

  2. GatewayConfig

    • The resource is no longer exposed; the endpoints GET /api/v2/admin/gateway-configs/id and GET /api/v2/admin/payment-methods/{code}/gateway-config are no longer available.

  3. Translation

    • All translation resources are no longer exposed, as each one is now integrated into its main resource.

  4. ChannelPriceHistoryConfig

    • The resource configuration is now managed by the Channel resource.
    • Removed endpoints:
      • GET /api/v2/admin/channel-price-history-configs/{id}
      • PUT /api/v2/admin/channel-price-history-configs/{id}

  5. ShopBillingData

    • The resource configuration is now managed by the Channel resource.
    • Removed endpoints:
      • GET /api/v2/admin/shop-billing-datas/{id}
      • GET /api/v2/admin/channels/{code}/shop-billing-data

  6. ZoneMember

    • The resource configuration is now managed by the Zone resource.
    • Removed endpoints:
      • GET /api/v2/admin/zone-members/{id}
      • GET /api/v2/admin/zones/{code}/members

  7. ProductOptionValueTranslation

    • A new resource configuration has been added for the ProductOptionValueTranslation resource it is now possible to manage translations for product option values.

Request Body and Response Updates

Request Payload Changes

ChannelPriceHistoryConfig

Management for ChannelPriceHistoryConfig has been moved to the Channel resource. The PUT request for Channel now includes channelPriceHistoryConfig fields:

Updated Channel PUT Request Body:

        "menuTaxon": "home-accessories",
    +   "channelPriceHistoryConfig": {
    +       "lowestPriceForDiscountedProductsCheckingPeriod": 30,
    +       "lowestPriceForDiscountedProductsVisible": true,
    +       "taxonsExcludedFromShowingLowestPrice": ["clearance", "seasonal"]
        }

ShopBillingData

ShopBillingData is now managed within the Channel resource and is no longer accessible directly. Retrieving ShopBillingData is now done through the Channel resource.

ProductAttribute

position is now included in the ProductAttribute request.

    {
        "code": "BRAND_ATTRIBUTE",
        "type": "text",
        "configuration": ["visible"],
    +   "position": 0,
        "translatable": true,
        "translations": {
            "en_US": "Brand",
            "fr_FR": "Marque",
            "es_ES": "Marca"
        }
    }

ProductImage

position has been added to the ProductImage request.

    {
        "productVariants": ["https://example.com/product-variant-1"],
        "type": "thumbnail",
    +   "position": 0
    }

Response Changes

Channel

    -   "shopBillingData": "\/api\/v2\/admin\/shop-billing-datas\/{id}",
    +   "shopBillingData": {
    +       "@type": "ShopBillingData",
    +       "company": "Sylius Inc.",
    +       "taxId": "123456789",
    +       "countryCode": "US",
    +       "street": "123 Commerce St.",
    +       "city": "eCommerce City",
    +       "postcode": "12345"
    +   }
    -  "channelPriceHistoryConfig": "/api/v2/admin/channel-price-history-configs/{id}"
    +  "channelPriceHistoryConfig": {
    +      "lowestPriceForDiscountedProductsCheckingPeriod": 30,
    +      "lowestPriceForDiscountedProductsVisible": true,
    +      "taxonsExcludedFromShowingLowestPrice": ["clearance", "seasonal"]
    +  }

Order

  • id has been removed from shop GET responses.
  • orderNumber has been removed from orders in shop item GET.
  • channel has been added to orders in shop item GET.
  • customerEmail is now exposed in the order GET response for shop.
  • state has been added to the order GET response for shop.
  • customerIp has been added to the admin serialization configuration.
    +   "channel": "/api/v2/shop/channels/WEB",
    +   "customer": {
    +       "@id": "/api/v2/shop/customers/123",
    +       "@type": "Customer",
    +       "email": "oliver@example.com"
    +   },
    +   "state": "cart",
    +   "customerIp": "192.168.1.2",
    -   "id": 1

OrderItemUnit

The sylius:admin:order_item_unit:show serialization group has been removed as endpoints for OrderItemUnit are no longer exposed.

Translations

id has been removed from serialization for all translation resources.

Example: ShippingMethod Get Response:

    "translations": {
        "en_US": {
            "@id": "/api/v2/admin/shipping-method-translations/1",
            "@type": "ShippingMethodTranslation",
    -       "id": 1,
            "name": "Standard Shipping",
            "description": "Delivery within 5-7 business days"
        }
    }

ProductAssociationType

id is no longer exposed on the shop GET endpoint.

    {
        "@context": "/api/v2/contexts/ProductAssociationType",
        "@id": "/api/v2/shop/product-association-types/similar_products",
        "@type": "ProductAssociationType",
    -   "id": 1,
        "code": "similar_products",
        "name": "Similar Products"
    }

ProductImage

position has been added to the ProductImage response for both shop and admin views.

    {
        "@context": "/api/v2/contexts/ProductImage",
        "@id": "/api/v2/admin/products/MUG/images/1",
        "@type": "ProductImage",
        "id": 1,
        "owner": "/api/v2/admin/products/MUG",
        "type": "thumbnail",
        "path": "https://example.com/images/sylius_original_thumbnail.jpg",
        "productVariants": ["/api/v2/admin/product-variants/MUG_BLUE"],
    +   "position": 0
    }

ProductOption

id has been removed from serialization.

    {
        "@context": "/api/v2/contexts/ProductOption",
        "@id": "/api/v2/admin/product-options/COLOR",
        "@type": "ProductOption",
    -   "id": 1,
        "code": "COLOR",
        "position": 0,
        "values": [
            "/api/v2/admin/product-options/COLOR/values/COLOR_BLUE",
            "/api/v2/admin/product-options/COLOR/values/COLOR_RED"
        ],
        "translations": {
            "en_US": {
                "@id": "/api/v2/admin/product-options/COLOR/translations/en_US",
                "@type": "ProductOptionTranslation",
                "name": "Color"
            }
        }
    }

ProductOptionValue

id has been removed from serialization.

    {
        "@context": "/api/v2/contexts/ProductOptionValue",
        "@id": "/api/v2/admin/product-option-values/COLOR_BLUE",
        "@type": "ProductOptionValue",
    -   "id": "1",
        "code": "COLOR_BLUE",
        "option": "/api/v2/admin/product-options/COLOR",
        "translations": {
            "en_US": {
                "value": "Blue"
            }
        },
        "value": "Blue"
    }

Province

The sylius:admin:province:index serialization group has been added for the index response.

ShopBillingData

id has been removed from serialization, and the sylius:admin:shop_billing_data:show serialization group has been removed. Company, taxId, countryCode, street, city, and postcode are now exposed on channels admin index and show views.

Example: Channel Get Response

    "shopBillingData": {
        "@type": "ShopBillingData",
    -   "id": 1,
        "company": "Web Channel Company",
        "taxId": "WCH123456",
        "countryCode": "EN",
        "street": "123 Web St.",
        "city": "Web City",
        "postcode": "00000"
    },

ZoneMember

id and belongsTo have been removed from serialization, and code has been added to the response for zones admin index and show. The ZoneMember get endpoint has been removed and is now accessible only through the Zone.

Example: Zone Get Response:

    {
        "@context": "/api/v2/contexts/Zone",
        "@id": "/api/v2/admin/zones/WD",
        "@type": "Zone",
    -   "id": 1,
        "code": "WD",
        "name": "WORLD",
        "type": "country",
        "scope": "all",
        "members": [
    -       "/api/v2/admin/zone-members/@integer@",
    -       "/api/v2/admin/zone-members/@integer@",
    -       "/api/v2/admin/zone-members/@integer@"
    +       {"@type": "ZoneMember", "code": "NL"},
    +       {"@type": "ZoneMember", "code": "BE"},
    +       {"@type": "ZoneMember", "code": "PL"}
        ]
    }