Concept - Customer REST API (valid to 7.10)

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	Representational state transfer
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: Individual or household (individual customer), or A business (business customer). 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: With single customer - simply put the user and customer are one thing With group customer - an associate to an organization

References

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	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.	Reference - Address Check REST API 1.0.0
/customers/-/credentials/question	A resource that provides functionality for changing the customer's security question.	Reference - Authentication REST API 1.0.1
/customers/-/credentials/password	A resource to change business customer's password.	Reference - Authentication REST API 1.0.1
/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.	Reference - Notification REST API 1.0.0
/customers/-/wishlists	A resource that allows management of customer's wishlists.	Reference - Wish List REST API 1.0.0
/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	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.	Reference - Address Check REST API 1.0.0
/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	Reference - Authentication REST API 1.0.1
/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.	Reference - Notification REST API 1.0.0
/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:

Naming Conventions

<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" />

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.