Skip to content

UPGRADE-API-2.1.md

Latest commit

 

History

History
217 lines (186 loc) · 6.31 KB

UPGRADE-API-2.1.md

File metadata and controls

217 lines (186 loc) · 6.31 KB

UPGRADE FROM 2.0 TO 2.1

Modified responses

Order

Various admin and shop Order responses have been modified to include the checkoutCompletedAt date and a promotionCoupon object. For the details of where these properties are available, check the Order's serialization context.

    "@context": "\/api\/v2\/contexts\/Order",
    "@id": "\/api\/v2\/shop\/orders\/token",
    "@type": "Order",
    ...
+   "promotionCoupon": {
+       "@id": "\/api\/v2\/shop\/promotion-coupons\/XYZ2",
+       "@type": "PromotionCoupon",
+       "code": "XYZ2"
+   },
+   "checkoutCompletedAt": null,
    ...

Product

The shop responses of Product index and show have been modified to include the default variant as a serialized object under the defaultVariantData property.

    "@context": "\/api\/v2\/contexts\/Product",
    "@id": "\/api\/v2\/shop\/products\/product-code",
    "@type": "Product",
    ...
    "defaultVariant": "\/api\/v2\/shop\/product-variants\/MUG_BLUE",
+   "defaultVariantData": {
+       "@context": "\/api\/v2\/contexts\/ProductVariant",
+       "@id": "\/api\/v2\/shop\/product-variants\/MUG_BLUE",
+       "@type": "ProductVariant",
+       "name": "Blue Mug",
+       "inStock": true,
+       "price": 2000,
+       "originalPrice": 3000,
+       "lowestPriceBeforeDiscount": null
+   }

2 new groups have been added for the purpose of serializing of the default variant specifically:

  • sylius:shop:product:index:default_variant
  • sylius:shop:product:show:default_variant

New filters for existing endpoints

Product

A new compound filter has been added to the shop Product index endpoint to retrieve associated products of either a product or/and an association type. The filter can be used by adding an association[ownerCode] or association[typeCode] query parameter to the request. Adding both at once will result in a logical AND operation, limiting the result to only products associated with the given owner and within the association type.

GET /api/v2/shop/products?association[ownerCode]={example-product-code}&association[typeCode]={example-association-type-code}

New endpoints

ProductOption

A new index endpoint has been added to the shop to retrieve the list of available product options.

GET /api/v2/shop/product-options

Which results in:

{
    "@context": "\/api\/v2\/contexts\/ProductOption",
    "@id": "\/api\/v2\/shop\/product-options",
    "@type": "hydra:Collection",
    "hydra:totalItems": 2,
    "hydra:member": [
        {
            "@id": "\/api\/v2\/shop\/product-options\/COLOR",
            "@type": "ProductOption",
            "code": "COLOR",
            "name": "Color"
        },
        {
            "@id": "\/api\/v2\/shop\/product-options\/SIZE",
            "@type": "ProductOption",
            "code": "SIZE",
            "name": "Size"
        }
    ],
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "\/api\/v2\/shop\/product-options{?productCode}",
        "hydra:variableRepresentation": "BasicRepresentation",
        "hydra:mapping": [
            {
                "@type": "IriTemplateMapping",
                "variable": "productCode",
                "property": "productCode",
                "required": false
            }
        ]
    }
}

The result can be filtered by the productCode query parameter, which limits the options to those that are available for the given product.

ProductOptionValue

A new index endpoint has been added to the shop to retrieve the list of available product option values.

GET /api/v2/shop/product-option-values

Which results in:

{
    "@context": "\/api\/v2\/contexts\/ProductOptionValue",
    "@id": "\/api\/v2\/shop\/product-option-values",
    "@type": "hydra:Collection",
    "hydra:totalItems": 4,
    "hydra:member": [
        {
            "@id": "\/api\/v2\/shop\/product-options\/COLOR\/values\/COLOR_BLUE",
            "@type": "ProductOptionValue",
            "code": "COLOR_BLUE",
            "option": "\/api\/v2\/shop\/product-options\/COLOR",
            "value": "Blue"
        },
        ...
        {
            "@id": "\/api\/v2\/shop\/product-options\/SIZE\/values\/SIZE_LARGE",
            "@type": "ProductOptionValue",
            "code": "SIZE_LARGE",
            "option": "\/api\/v2\/shop\/product-options\/SIZE",
            "value": "Large"
        }
    ],
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "\/api\/v2\/shop\/product-option-values{?productCode}",
        "hydra:variableRepresentation": "BasicRepresentation",
        "hydra:mapping": [
            {
                "@type": "IriTemplateMapping",
                "variable": "productCode",
                "property": "productCode",
                "required": false
            }
        ]
    }
}

The result can be filtered by the productCode query parameter, which limits the option values to those that are available for the given product, regardless whether they're used within it's variants or not.

ProductAssociationType

A new index endpoint has been added to the shop to retrieve the list of available association types.

GET /api/v2/shop/product-association-types

Which results in:

{
	"@context": "/api/v2/contexts/ProductAssociationType",
	"@id": "/api/v2/shop/product-association-types",
	"@type": "hydra:Collection",
	"hydra:totalItems": 20,
	"hydra:member": [
		{
			"@id": "/api/v2/shop/product-association-types/similar-products",
			"@type": "ProductAssociationType",
			"code": "similar-products",
			"name": "Similar Products"
		},
        ...
		{
			"@id": "/api/v2/shop/product-association-types/accessories",
			"@type": "ProductAssociationType",
			"code": "accessories",
			"name": "Accessories"
		}
	],
	"hydra:search": {
		"@type": "hydra:IriTemplate",
		"hydra:template": "/api/v2/shop/product-association-types{?productCode}",
		"hydra:variableRepresentation": "BasicRepresentation",
		"hydra:mapping": [
			{
				"@type": "IriTemplateMapping",
				"variable": "productCode",
				"property": "productCode",
				"required": false
			}
		]
	}
}

Each of the returned product association types has at least one enabled associated product. The productCode filter can be used to limit the association types to those that have an association with the given product set as the owner.