Guide - 7.10 REST API Changes

1 Intershop Commerce Management REST API

There are the following changes in basket/order related REST APIs to:

  • Get a stringent naming scheme (SalesPricingRO, ShippingPricingRO, TotalsRO)
  • Avoid errors in generated Swagger schema (MoneyRO, QuantityRO)
  • Be prepared for future use (TaxItemRO, JurisdictionRO, ImpositionRO)
VersionAPIElementChangeCompatibilityComment
7.10.7.3

Order Submission/OrderHistory (beta)

Note

This API is a beta version and still subject to changes.

MoneyROAttribute currency is no longer read-only.incompatible
Attribute value is no longer read-only.incompatible
QuantityROAttribute unit is no longer read-only.incompatible
Attribute value is no longer read-only.incompatible
SalesPricingROAttribute price is replaced by undiscountedPrice incompatibleThe line item price (single base price x quantity) w/o any discounts
Attribute discountedPrice is replaced by price incompatibleThe line item price (single base price x quantity) w granted item value discounts
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice
incompatibleThe base price of one (single base price / quantity)  single item w/o any discounts
Attribute discountedSingleBasePrice is replaced by singleBasePrice incompatibleThe base price of one item w/ granted item discounts broken down to one item
Attribute discountedSingleBasePriceRemainder is replaced by singleBasePriceRemainder incompatibleThe remainder of the operation that calculates the singleBasePrice.
ShippingPricingROAttribute shippingTotal is replaced by undiscountedShippingTotal incompatibleThe accumulated shipping costs of the line item w/o any shipping discounts.
TotalsROAttribute itemTotal is replaced by undiscountedItemTotal incompatibleThe accumulated line item totals w/o any discounts
Attribute discountedItemTotal is replaced by itemTotal incompatibleThe accumulated line item total w/ all granted item value discounts
Attribute shippingTotal is replaced by undiscountedShippingTotal incompatibleThe accumulated shipping costs/charges w/o any discounts
Attribute discountedShippingTotal is replaced by shippingTotal incompatibleThe accumulated shipping costs/charges w/ all granted shipping discounts
New attribute paymentCostsTotalcompatibleAccumulated payment costs of the order
AddressRONew attribute companyName1 compatibleFirst part of addressee's company name
New attribute companyName2 compatibleSecond part of addressee's company name
TaxItemRO

New attribute taxId compatibleFor future use
New attribute taxName compatibleFor future use
New record ImpositionRO compatibleFor future use
JurisdictionRONew attribute value compatibleFor future use
Attribute level is required nowincompatible
ImpositionRONew attribute value compatibleFor future use
New attribute type compatibleFor future use

2 Storefront REST API

2.1 Basket V1 REST API

In the Storefront Basket V1 REST APIs there are the following changes:

  • Get a stringent naming scheme (LineItemRO, LineItemTotalsRO, BasketTotalsRO).
  • Simplify handling of custom attributes (ExtensibleRO).
VersionAPIElementChangeCompatibilityComment
7.10.7.3







Basket V1 (beta)

Note

This API is a beta version and still subject to changes.

LineItemROAttribute price is replaced by undiscountedPrice and has been moved to Element LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe line item price (single base price x quantity) w/o any discounts
Attribute discountedPrice is replaced by price and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe line item price (single base price x quantity) w granted item value discounts
Attribute singleBasePrice is replaced by undiscountedSingleBasePrice and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe base price of one (single base price / quantity) single item w/o any discounts
Attribute discountedSingleBasePrice is replaced by singleBasePrice and has been moved to LineItemPricingRO (former LineItemTotalsRO).
incompatibleThe base price of one item w/ granted item discounts broken down to one item
Attribute totals is replaced by pricing.

LineItemTotalsROElement has been renamed to LineItemPricingRO.incompatible
Attribute totals has been replaced by price.

BasketTotalsRO


Attribute itemTotal is replaced by undiscountedItemTotal. incompatibleThe accumulated line item totals w/o any discounts
Attribute discountedItemTotal is replaced by itemTotal.incompatibleThe accumulated line item total w/ all granted item value discounts
Attribute shippingTotal is replaced by undiscountedShippingTotal.incompatibleThe accumulated shipping costs/charges w/o any discounts
Attribute discountedShippingTotal is replaced by shippingTotal.incompatibleThe accumulated shipping costs/charges w/ all granted shipping discounts
Attribute paymentCostTotal is replaced by paymentCostsTotal.

ExtensibleRO (and all inheriting elements: AddressRO, BasketRO, LineItemRO, ShippingMethodRO)

Method ExtensibleRO::getAttributes() : Map<String, Collection<String>> has been replaced by ExtensibleRO::getAttributes() : Collection<AttributeRO<?>>.

incompatibleAttributes are contained in the data section of JSON payload of related elements instead of the includes section.

2.2 Storefront Business Customer User List / User Item REST API

Storefront Business Customer User List / User Item REST API was extended:

  • Business Customer Users List resource GET method previously showed the current logged user. It was changed to list all actual users of the customer;
  • Added POST method to Business Customer Users List resource to create one or multiple new users for the customer;
  • Added DELETE method to Business Customer User Item resource to remove customer's user;
  • Altered PUT method of Business Customer User Item resource - previously it only allowed the current logged user to change their own attributes; now admin user can change values of other users which belong to the same customer.
VersionAPIElementChangeCompatibility
7.10.7.3

Business Customer User List / User ItemUserRONew method getBirthdayDate() : Datecompatible
SMBCustomerUserRO

New methods:

getPreferredInvoiceToAddressUrn() : String

setPreferredInvoiceToAddressUrn(String)

getPreferredShipToAddressUrn() : String

setPreferredShipToAddressUrn(String)

compatible

New classes in app_sf_rest_smb cartridge

SMBCustomerUserROCollection

UserLinkRO

UserLinkROCollection

compatible

2.3 Storefront Product and Category REST API


VersionAPIElementChangeCompatibilityComment
7.10.23.0Product

ProductsResource

ProductFiltersResource

New query parameter MasterSKU addedcompatible

MasterSKU can now be indexed in the search index, similar to MasterUUID. This is needed so MasterSKU can be used in the REST API, e.g. to filter /products and /productfilters for a given variation master. (The REST API only handles skus, not UUIDs.)

  • Add new attribute "MasterSKU" to the index, with the same settings as "MasterUUID".
    • Recommendation: Keep the name "MasterSKU". If not, make a note of the new defined name so you can use it later in the REST API - this is the name of the query parameter.
    • Rebuild the search index.
  • Now you can use the “MasterSKU” query parameter as described in the REST API documentation.
7.10.23.0Product

ProductsResource

ProductFiltersResource

if configured: new sort order of resultscompatible

Variation products on variation master pages, as well as in the REST API (/products?MasterSKU=<sku>) can now be sorted as defined in the backoffice, if no other sorting is specified. This requires configuration of the search index.

  • create new index attribute
    • name: VariationPosition
    • data provider: ProductPO
    • data type: Double
  • rebuild search index

Note: If this is not done, the sorting remains as it is right now.

7.10.23.0ProductProductListResource

Support for multiple comma-separated IDs for parameter attributeGroup

New field attributeGroups in result if multipe IDs were given.

compatibleIf multiple IDs are given, then in the result, the field attributeGroup will be empty, and attributeGroups is used.
7.10.23.0ProductAttributeGroupRONew field displayName addedcompatible

7.10.21

Product

SearchIndexFilterResource

SearchIndexFilterListResource

Resources are now deprecated.

compatible


7.10.21ProductProductFiltersResource

Resource is introduced.

compatibleA new resource /productfilters was introduced for the filter REST API. It replaces the (now deprecated) /filters resource.
7.10.21.0ProductProductRONew field supplierSKU added.compatible
7.10.18.0CategoryCategoryROCategory endpoint now support category references as a category id, replacing the previous categoryRef query parameter. Format: /categories/<category id or ref>incompatible
7.10.17.0ProductProductRO

New query parameter extended added

New field variationAttributeValuesExtended added

compatible
7.10.17.0ProductAttachmentRONew field effectiveUrl addedcompatible
7.10.17.0Category and CategoryListCategoryRONew query parameter omitHasOnlineProducts addedcompatible
7.10.15.2Product ListProductRONew attribute in attrs section retailSet
compatible
7.10.15.2Category and CategoryListCategoryROAdd functionality for caching the /categories callcompatible
7.10.10.2Product / Product Line ItemDefaultCategoryROExtend appendProductSKUToPath(String path, ProductBO product) to show default categorycompatible
7.10.9.0Product and Category ListLinkRONew attribute in attrs section: packingUnit compatible
7.10.5.4Product List / Product Line ItemLinkRONew attribute in attrs section: availableStock compatible
7.10.5.3Product ListAttributeGroupRO

New method getRESTAvailableAttributeGroups(ProductBO product)

compatibleRelated: Adding flag in the backoffice if attribute groups should be available in REST.
7.10.5.3Product and Category ListLinkRONew attributes in attrs section: minOrderQuantity  and inStock compatible

2.4 Storefront Customer REST API

VersionAPIElementChangeCompatibilityComment
7.10.15.0

customer/{customerKey}/credentials/passwordCustomerPasswordRO

New mandatory attribute currentPassword.

compatibleIn order to keep the old behavior it is possible to make currentPassword optional by setting"PasswordUpdateSkipOldPasswordValidation" preference to "true".


CredentialsHandlerSignature of method validatePassword changed from validatePassword(UserBO userBO, String password) to validatePassword(UserBO userBO, CustomerPasswordRO passwordRO).incompatible

2.5 Storefront Security REST API

VersionAPIElementChangeCompatibilityComment
7.10.15.0

securitypassword

Added new sub-resource "password" allowing to set new password - part of the "Forgot Password" feature.

New REST resource com.intershop.sellside.rest.common.capi.resource.credentials.PasswordResetResource with one POST method resetPassword.

New resource object com.intershop.sellside.rest.common.capi.resourceobject.PasswordResetRO

New interface com.intershop.sellside.rest.common.capi.resource.credentials.handler.PasswordResetHandler

compatible

securityreminderChanged PasswordReminderResource to require security question answer, firstName and lastName only in case Security Question feature is activated.compatible

2.6 Storefront Configuration REST API

VersionAPIElementChangeCompatibility
7.10.20.0

Configuration V1 (beta)

Note

This API is a beta version and still subject to changes.


ConfigurationRO

Change of the response data structure from list to map representation.

Payload before the change:
{
    "data":
		[
        	{
        	    "applicationType": "intershop.B2CResponsive",
            	"default": true,
	            "id": "application",
	            "urlIdentifier": "-"
    	    },...
		]
}
Payload after the change:
{
    "data": 
		{
        	"application": {
        	    "applicationType": "intershop.B2CResponsive",
        	    "default": true,
        	    "id": "application",
        	    "urlIdentifier": "-"
        	},...
		}
}
incompatible

2.7 Storefront CMS REST API

VersionAPIElementChangeCompatibilityComment
7.10.19.2CMS REST API
The REST API documentation was extended to explain the proper usage of personalized requests for the CMS REST API.compatible
7.10.18.1CMS REST API

PageTreeResource

Resource is introduced to expose the page hierarchy.

compatible

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets