breaking-changes-in-web-api-5.md

✔️ Breaking changes in Web API 5

Authentication

HMAC authentication is no longer supported. For the highest level of interoperability with generic clients, the Web API now uses Basic authentication over HTTPS, as recommended by the OData protocol version 4.0.

Querying related entities

The following path is no longer supported:

GET /EntitySet({id})/RelatedEntity({relatedId})

Simply use the endpoint for the related entity directly.

{% code title="Example" %}

old /Customers(1)/Addresses(2)
new /Addresses(2)

{% endcode %}

Querying properties

The following path is no longer supported:

GET /EntitySet({id})/PropertyName

Use the more flexible $select instead:

{% code title="Example" %}

old /Categories(14)/Name
new /Categories(14)?$select=Name

{% endcode %}

Response of PUT and PATCH requests

For PUT and PATCH requests, the HTTP header Prefer with the value return=representation must be sent to get a status code 200 with an entity content response. This is the default behavior of AspNetCore.OData v.8, otherwise 204 No Content is returned.

Return types of media endpoints

• /MediaFiles returns the type FileItemInfo that wraps and enriches the media file entity.
• /MediaFolders returns the type FolderNodeInfo that wraps and enriches the media folder entity.

Both are flattened objects without navigation properties.

Request parameters

Request parameters must be written in camel case.

{% code title="Example" %}

old /MediaFiles/GetFileByPath {"Path": "catalog/my-image.jpg"}
new /MediaFiles/GetFileByPath {"path": "catalog/my-image.jpg"}

{% endcode %}

Entity fulfillment

The query string parameter SmNetFulfill has been renamed to SmApiFulfill.

Changed endpoints

Old endpoint -> New endpoint	Remarks
GET MediaFiles/Download({Id}) -> GET MediaFiles/DownloadFile({id})
POST OrderItems({id})/Infos -> GET OrderItems/GetShipmentInfo({id})
POST Orders({id})/Infos -> GET Orders/GetShipmentInfo({id})
POST Orders({id})/Pdf -> GET Orders/DownloadPdf({id})
GET Payments/Methods -> GET PaymentMethods/GetAllPaymentMethods({active},{storeId})	New method. Now returns a list of payment method system names.
ProductPictures/... -> ProductMediaFiles/...	The controller name has changed.
Products/ProductPictures -> Products/ProductMediaFiles	The navigation property name has changed.
POST Uploads/ProductImages -> POST Products/ProductMediaFiles	New method. Now returns a list of ProductMediaFile. SKU, GTIN or MPN to identify the product can optionally be sent via query string. ContentDisposition parameter pictureId renamed to fileId.
POST Products/FinalPrice|LowestPrice -> POST Products/CalculatePrice	New method. Now returns CalculatedProductPrice.

{% hint style="info" %} Notes:

• Route /api/v1/ no longer exists.
• The parameterization has been changed to support Swagger. {% endhint %}

Changed response header names

Old -> new name	Remarks
SmartStore-Net-Api-... -> Smartstore-Api-...	Name prefix changed.
SmartStore-Net-Api-HmacResultId -> Smartstore-Api-AuthResultId	New values.
SmartStore-Net-Api-HmacResultDesc -> Smartstore-Api-AuthResultDesc	New values.
SmartStore-Net-Api-MissingPermission -> -	Obsolete, no longer sent.