This document describes the concept behind the customer related functionality part of the REST API. It covers the logical similarity between the REST API customer extension and the standard storefront applications, the resource, resource objects and related classes structure as well as concepts behind validation and data handling introduces 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 existing the REST API is taking a two applications approach, much like the standard storefront. Instead of having a single REST API, it is now split on B2C and B2B related ones which are assigned to corresponding applications. Common customer functionality which is not dependent on the capabilities of the customer type is shared between the two.
The present document is addressed to developer who want to extend and modify the customer REST API of Intershop 7. Also it is a good starting point for anyone aiming to create a application based on REST, e.g., a mobile application, and want to have an overview about how resources are structured.
The functionality described here covers the process around customer self management - self registration, profile and address management.
Albeit there are some specific implementation details, customer related resources are implemented by following the general REST API approach. Before continue reading you should get yourself familiar with the REST API Concept and Cookbook - REST Framework 7.5. Knowledge about what customers are and what capabilities they have depending on their customer type is a must.
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 | In the shop manager's perspective, a customer is an actor at the selling side of e-commerce environment who, among others, browses through the storefront orders products and services returns products creates and manages an own customer account subscribes or unsubscribes for newsletters ... In Intershop 7, customers are categorized in customer types and can be grouped in customer segments. |
customer type | In Intershop 7, customer types categorize customers. They indicate whether a customer represents an
Intershop 7's features can differ according to the customer type. For example, they can display either gross prices or net prices, provide additional profile information, hide certain functionality, etc. |
individual customer | In Intershop 7, a customer type that represents an individual person or household. As opposed to business customers, individual customers are assigned exactly one user are presented gross prices by default. |
business customer | In Intershop 7, a customer type that represents a business. As opposed to individual customers, business customers can be assigned multiple users, which can be managed are presented net prices by default. |
user | The meaning vary depending on the customer type:
|
Concept - Customer REST API (valid to 7.9)
Concept - REST Framework
Cookbook - REST Framework 7.5
Reference - WebShop REST API
Concept - Customers and Users
The current concept in functionality separation is realized with two applications - B2C Webshop and B2B Webshop. Those applications have a lot in common, code wise, but concrete parts of them are separated in order to cover the business processes required. This separation is realized by having two different set of cartridges loaded to the applications.
As shown on the diagram the cartridges app_sf_webshop_b2c and app_sf_webshop_smb 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 had just the B2C REST API, intershop.B2CWebShop.RESTAPI
, defined in sld_ch_b2c_rest cartridge.In addition now there is a B2B REST API - intershop.B2BWebShop.RESTAPI
. It is defined in the same cartridge.
The APIs are defined with 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.
Some resources are shared between the different APIs and some resources are unique for an API.
Almost all B2B resource require that the REST client is using a valid credentials of given user of a business customers and authenticate said user to the system.
The table bellow shows to the important resources available in the B2B REST API. The Authentication
column indicates if the client has to be authenticated before accessing the resource. Dynamic
column indicates that this resource represent a collection of objects and every element of this collection can be accessed by its ID. For complete list of URIs/resource check the Reference - WebShop REST API (7.4 - 7.4 CI).
Resource | Description | Requires authentication | Dynamic sub-resource | Reference |
---|---|---|---|---|
/customers/ | A resource to provide functionality for customer's self registration. | |||
/customers/-/ | A resource to provide functionality for retrieving customer's details. | REST API - Company profile details (until 7.8) | ||
/customers/-/addresses | A resource to provide functionality for customer's address management. | REST API - Customer addresses list (until 7.7) | ||
/customers/-/addresses/<address-id>/suggestions/ | A resource to provide functionality for possible addresses suggestions of given address. | REST API - Get address' list of links to suggested addresses | ||
/customers/-/users/- | A resources that allows viewing and updating of the profile details of currently logged in user of a business customer. | REST API - Profile details of user of a business customer (until 7.8) | ||
/customers/-/users/-/credentials/password | A resource to change business customer's user's password. | REST API - Update password of business customer's user | ||
/customers/-/users/-/credentials/question | A resource to change business customer's user's security question | REST API - Update security question of business customer's user | ||
customers/-/users/-/giftcardsandcertificates | A resource to view gift cards and certificates used or available by/to given user and check their balance. | REST API - Get the gift cards and certificates SMB REST API - Get the balance of a specific gift card or certificate SMB | ||
/customers/-/users/-/notifications/stock | A resource that allows management of product notification for availability. | REST API - Create product stock notification SMB REST API - Update product stock notification SMB | ||
/customers/-/users/-/notifications/price | A resource that allows management of product notification for reaching certain price threshold. | REST API - Get product price notification details SMB REST API - Update product price notification SMB | ||
/customers/-/users/-/wishlists | A resource that allows management of user's wishlists. | REST API - Get list of wish lists of business customer REST API - Create new business customer wish list REST API - Update business customer wish list | ||
/customers/-/users/-/wishlists/<wishlist-id>/share | A resource for sharing private wishlist with someone. | REST API - Share wish list of business customer's user with given recipient | ||
/customers/-/users/-/wishlists/<wishlist-id>/settings | A resource for managing wishlist settings. |
In B2C most of the resources require that the client is using a real customer that is authenticated.
The table bellow shows some of the important resources available in the B2C REST API. The Authentication
column indicates if the client has to be authenticated before accessing the resource. Dynamic
column indicates that this resource represent a collection of objects and every element of this collection can be accessed by its ID. For complete list of URIs/resource check the Reference - WebShop REST API (7.4 - 7.4 CI).
Resource | Description | Requires authentication | Dynamic sub-resource | Reference |
---|---|---|---|---|
/customers/ | A resource to provide functionality for customer's self registration. | |||
/customers/-/ | A resource to provide functionality for retrieving customer's details. | |||
/customers/-/addresses | A resource to provide functionality for customer's address management. | REST API - Customer addresses list (until 7.7) | ||
/customers/-/addresses/<address-id>/suggestions/ | A resource to provide functionality for possible addresses suggestions of given address. | REST API - Get address' list of links to suggested addresses | ||
/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. | REST API - Update password | ||
/customers/-/credentials/question | A resource to change business customer's security question | REST API - Update security question | ||
customers/-/giftcardsandcertificates | A resource to view gift cards and certificates used or available by/to given customer and check their balance. | REST API - Get the gift cards and certificates B2C REST API - Get the balance of a specific gift card or certificate B2C | ||
/customers/-/notifications/stock | A resource that allows management of product notification for availability. | REST API - Create product stock notification B2C REST API - Delete product stock notification B2C REST API - Get product stock notification details B2C REST API - Update product stock notification B2C | ||
/customers/-/notifications/price | A resource that allows management of product notification for reaching certain price threshold. | REST API - Create product price notification B2C REST API - Get product price notification details B2C | ||
/customers/-/wishlists | A resource that allows management of customer's wishlists. | REST API - Get list of wish lists of private customer REST API - Get private customer wish list details | ||
/customers/-/wishlists/<wishlist-id>/share | A resource for sharing private wishlist with someone. | REST API - Share wish list of private customer with given recipient | ||
/customers/-/wishlists/<wishlist-id>/settings | A resource for managing wishlist settings. |
As resources are realized with components (see Concept - REST Frameworkfor 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 specifies that the suggestion item resource's instance is with name intershop.B2CWebShop.RESTAPI.CustomerAddressItemSuggestionItemResource
. To add it to a REST API, both the B2B or the B2C, you only need to add it as sub-resource somewhere.
<fulfill requirement="itemResource" with="intershop.B2CWebShop.RESTAPI.CustomerAddressItemSuggestionItemResource" />
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.