Introduction
This document describes the concept behind the customer-related functionality of the REST API.
It covers the logical similarity between the REST API customer extension and standard storefront applications, the resource, resource objects, and associated class structure as well as the concepts behind validation and data processing introduced for this extension.
The goal with extending the REST API is to provide custom/REST clients with means to manage and retrieve customer information and details.
To achieve flexible functionality, the REST API takes a two-application approach, similar to the standard storefront. Instead of having a single REST API, it is now split into B2C and B2B-related ones which are assigned to the corresponding applications. Common customer functionality which is not dependent on the capabilities of the customer type is shared between the two.
This document is aimed at developers who want to extend and modify the customer REST API of Intershop 7. It is also a good starting point for anyone who wants to create an application based on REST, such as a mobile application, and wants to get an overview of the resource structure.
The functionality described here covers the process around customer self management - self registration, profile management and address management.
Albeit there are some specific implementation details, customer-related resources are implemented by following the general REST API approach. Before reading any further, familiarize yourself with the REST API Concept and Cookbook - REST Framework.
Knowledge about what customers are and what capabilities they have depending on their customer type is a must.
Glossary
Term | Explanation |
|---|---|
REST | |
Resource | A server-side object that handles the request and is identified by the URI |
ResourceObject (RO) | A data object that is serialized/deserialized and used to transfer structured data between client and server |
Customer | From the shop manager's point of view, a customer is an actor on the sales side of the e-commerce environment who browses through the storefront, orders products and services, returns products, creates and manages his or her customer account, signs up for or unsubscribes from newsletters. In Intershop 7, customers are categorized into customer types and can be grouped into customer segments. |
Customer type | In Intershop 7, customer types categorize customers. They indicate whether a customer represents an:
The functions of Intershop 7 can differ depending on the customer type. For example, customers can have either gross or net prices displayed, provide additional profile information, hide certain features, etc. |
Individual customer | A customer type that represents an individual person or household. Unlike business customers, individual customers are assigned to exactly one user and have gross prices displayed by default. |
Business customer | A customer type that represents a business. Unlike individual customers, business customers can have multiple manageable users assigned to them and have net prices displayed by default. |
User | The meaning varies depending on the customer type:
|
References
- Cookbook - Customer REST API
- Concept - REST Framework
- Cookbook - REST Framework
- Reference - WebShop REST API
- Concept - Customers and Users
B2C and B2B REST APIs
The current concept in functionality separation is realized with two applications - B2C Webshop and B2B Webshop. These applications have a lot in common code-wise, but specific parts of them are separated to cover the required business processes.
This separation is realized by having two different set of cartridges loaded to the applications.
As shown in the diagram, the app_sf_webshop_b2c and app_sf_webshop_smb cartridges are the ones that distinguish the B2C and B2B applications from one another.
The same approach is realized with the REST API. Pre-7.4.2 version of Intershop 7 only had the B2C REST API, intershop.B2CWebShop.RESTAPI, defined in sld_ch_b2c_rest cartridge. In addition, there is now a B2B REST API - intershop.B2BWebShop.RESTAPI. It is defined in the same cartridge.
The APIs are defined by the following code:
<instance name="intershop.B2CWebShop.RESTAPI" with="AppRootResourceAssignment">
<fulfill requirement="rootResource" with="intershop.B2CWebShop.RESTAPI.root" />
</instance>
<instance name="intershop.B2BWebShop.RESTAPI" with="AppRootResourceAssignment">
<fulfill requirement="rootResource" with="intershop.B2BWebShop.RESTAPI.root" />
</instance>
With this approach common functionality for customers, such as address management, can be implemented in a single place, sld_ch_b2c_rest for example, and reused later in extension cartridges.
Customer Resources
Some resources are shared between the different APIs and some resources are unique for an API.
B2C REST API
In B2C most of the resources require that the client uses a real customer that is authenticated.
The table below shows some of the important resources available in the B2C REST API. The Requires authentication column indicates if the client has to be authenticated before accessing the resource. The Dynamic sub-resource column indicates that this resource represents a collection of objects and every element of this collection can be accessed by its ID. For a complete list of URIs/resources, refer to Reference - Intershop Commerce Management 7.10 REST API.
Resource | Description | Requires authentication | Dynamic sub-resource | Reference |
|---|---|---|---|---|
/customers/ | A resource to provide functionality for customer's self registration. |
|
| Reference - Customer REST API 1.0.0 |
/customers/-/ | A resource to provide functionality for retrieving customer's details. |
|
| |
/customers/-/addresses | A resource to provide functionality for customer's address management. |
|
| |
| /customers/-/giftcardsandcertificates | A resource to view gift cards and certificates used or available by/to given customer and check their balance. |  | | |
/customers/-/addresses/<address-id>/suggestions/ | A resource to provide functionality for possible addresses suggestions of given address. |
|
| |
/customers/-/credentials/question | A resource that provides functionality for changing the customer's security question. |
|
| |
| /customers/-/credentials/password | A resource to change business customer's password. | |  | |
| /customers/-/notifications/stock | A resource that allows management of product notification for availability. | | | Reference - Notification REST API 1.0.0 |
| /customers/-/notifications/price | A resource that allows management of product notification for reaching certain price threshold. | | | |
| /customers/-/wishlists | A resource that allows management of customer's wishlists. | | | |
| /customers/-/wishlists/<wishlist-id>/share | A resource for sharing private wishlist with someone. | | | |
| /customers/-/wishlists/<wishlist-id>/settings | A resource for managing wishlist settings. |
|
|
B2B REST API
Almost all B2B resources require that the REST client uses valid credentials of a given user of a business customer and authenticate said user to the system.
The table below shows the important resources available in the B2B REST API. The Requires authentication column indicates if the client has to be authenticated before accessing the resource. The Dynamic sub-resource column indicates that this resource represents a collection of objects and every element of this collection can be accessed by its ID. For a complete list of URIs/resources, refer to Reference - Intershop Commerce Management 7.10 REST API.
REST resources for individual customer are also available for the B2B application. In the scope of this application, the designation /privatecustomers is used instead of the /customers. All subresources of the individual customer are also available to the resource privatecustomers.
This feature is available from Intershop 7.10.21.0.
Resource | Description | Requires authentication | Dynamic sub-resource | Reference |
|---|---|---|---|---|
/customers/ | A resource to provide functionality for customer's self registration. |
|
| Reference - Customer REST API 1.0.0 |
/customers/-/ | A resource to provide functionality for retrieving customer's details. |
|
| |
/customers/-/addresses | A resource to provide functionality for customer's address management. |
|
| |
| /customers/-/users/- | A resources that allows viewing and updating of the profile details of currently logged in user of a business customer. | | | |
| /customers/-/users/-/giftcardsandcertificates | A resource to view gift cards and certificates used or available by/to given user and check their balance. | | | |
/customers/-/addresses/<address-id>/suggestions/ | A resource to provide functionality for possible addresses suggestions of given address. |
|
| |
| /customers/-/users/-/credentials/password | A resource to change business customer's user's password. |
|
| Reference - Authentication REST API 1.0.1 |
| /customers/-/users/-/credentials/question | A resource to change business customer's user's security question |
|
| |
| /customers/-/users/-/notifications/stock | A resource that allows management of product notification for availability. |
|
| Reference - Notification REST API 1.0.0 |
| /customers/-/users/-/notifications/price | A resource that allows management of product notification for reaching certain price threshold. |
|
| |
| /customers/-/users/-/wishlists | A resource that allows management of user's wishlists. |
|
| Reference - Wish List REST API 1.0.0 |
| /customers/-/users/-/wishlists/<wishlist-id>/share | A resource for sharing private wishlist with someone. |
|
| |
| /customers/-/users/-/wishlists/<wishlist-id>/settings | A resource for managing wishlist settings. |
|
|
Naming Convention and Practices
As resources are realized with components (see Concept - REST Framework for more information) it is important that no resource is created as anonymous instance. In other words, the resource's instance has to be be created with explicitly set name and in addition the name has to be prefixed with the name of the REST API it belongs to. Take a look at the following example:
<instance
name="intershop.B2CWebShop.RESTAPI.CustomerAddressItemSuggestionItemResource"
with="CustomerAddressItemSuggestionItemResource">
<fulfill requirement="handler" with="intershop.WebShop.RESTAPI.CustomerAddressHandler" />
<fulfill requirement="currentCustomerProvider">
<instance with="CurrentCustomerProviderImpl" />
</fulfill>
</instance>
It clearly indicates that the Suggestion Item Resource instance has the name intershop.B2CWebShop.RESTAPI.CustomerAddressItemSuggestionItemResource. To add it to a REST API, both B2B or B2C, you only have to add it as a sub-resource somewhere:
<fulfill requirement="itemResource"
with="intershop.B2CWebShop.RESTAPI.CustomerAddressItemSuggestionItemResource" />