Concept - Customer REST API (11.2.0)

Introduction

This document describes the concept behind the customer-related functionality of the WebShop 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.

This document is aimed at developers who want to extend and modify the customer REST API of Intershop Commerce Management. 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 essential.

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 Commerce Management, customers are categorized into customer types and can be grouped into customer segments.
Customer type	In Intershop Commerce Management, 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 Commerce Management 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 - the user and customer are one and the same With group customer - an associate to an organization

References

REST API

Although there are different applications for B2C and B2B, there is only one REST API that contains both parts equally. See Concept - Headless Application Type - intershop.REST for further details.

The API is defined by the following code:

<instance name="intershop.WebShop.RESTAPI" with="AppRootResourceAssignment">
    <fulfill requirement="rootResource" with="intershop.WebShop.RESTAPI.root" />
</instance>

Customer Resources

The WebShop REST API provides endpoints for Private Customers as well as for Business Customers. This paragraph outlines the endpoints for both customer types.

Private Customers

Private customers (B2C scenario) are real individual customers that have to authenticate themselves against the REST API.

The table below shows some of the important resources. The Requires authentication column indicates whether 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	Corresponding REST API
/privatecustomers/	A resource to provide functionality for customer's self registration.	Customer REST API
/privatecustomers/-/	A resource to provide functionality for retrieving customer's details.
/privatecustomers/-/addresses	A resource to provide functionality for customer's address management.
/privatecustomers/-/giftcardsandcertificates	A resource to view gift cards and certificates used or available by/to given customer and check their balance.
/privatecustomers/-/addresses/<address-id>/suggestions/	A resource to provide functionality for possible addresses suggestions of given address.	Address Check REST API
/privatecustomers/-/credentials/question	A resource that provides functionality for changing the customer's security question.	Authentication REST API
/privatecustomers/-/credentials/password	A resource to change business customer's password.	Authentication REST API
/privatecustomers/-/notifications/stock	A resource that allows management of product notification for availability.	Notification REST API
/privatecustomers/-/notifications/price	A resource that allows management of product notification for reaching certain price threshold.	Notification REST API
/privatecustomers/-/wishlists	A resource that allows management of customer's wishlists.	Wish List REST API
/privatecustomers/-/wishlists/<wishlist-id>/share	A resource for sharing private wishlist with someone.
/privatecustomers/-/wishlists/<wishlist-id>/settings	A resource for managing wishlist settings.

Business Customers

A business customer (B2B scenario) consists of a customer (the company) and user (employees of the company). Almost all resources require that the REST client uses valid credentials of a given user to authenticate to the system.

The table below shows the important Business Customer resources that are available. 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	Corresponding REST API
/customers/	A resource to provide functionality for customer's self registration.	Customer REST API
/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.	Address Check REST API
/customers/-/users/-/credentials/password	A resource to change business customer's user's password.	Authentication REST API
/customers/-/users/-/credentials/question	A resource to change business customer's user's security question	Authentication REST API
/customers/-/users/-/notifications/stock	A resource that allows management of product notification for availability.	Notification REST API
/customers/-/users/-/notifications/price	A resource that allows management of product notification for reaching certain price threshold.	Notification REST API
/customers/-/users/-/wishlists	A resource that allows management of user's wishlists.	Wish List REST API
/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.WebShop.RESTAPI.PrivateCustomerAddressItemSuggestionItemResource"
    with="PrivateCustomerAddressItemSuggestionItemResource">
    <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.WebShop.RESTAPI.PrivateCustomerAddressItemSuggestionItemResource. To add it to the REST API, you have to add it as a sub-resource to a component file:

<fulfill requirement="subResource"
        with="intershop.WebShop.RESTAPI.PrivateCustomerAddressItemSuggestionItemResource" />

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.