1 Introduction

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.

1.1 Glossary

1.2 References

Concept - Customer REST API
Concept - REST Framework
Cookbook - REST Framework 7.5
Reference - WebShop REST API
Concept - Customers and Users

2 B2C and B2B REST APIs

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.

3 Customer Resources

Some resources are shared between the different APIs and some resources are unique for an API.

3.1 B2B REST 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).

3.2 B2C REST API

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.			REST API - Create private customer (until 7.7)
/customers/-/	A resource to provide functionality for retrieving customer's details.			REST API - Update private customer profile (until 7.8)
/customers/-/addresses	A resource to provide functionality for customer's address management.			REST API - Customer addresses list (until 7.7) REST API - Create new customer address (until 7.7) REST API - Update customer address (until 7.7) REST API - Delete customer address (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 REST API - Get suggested address details (until 7.7) REST API - Update address details as suggested (until 7.7)
/customers/-/credentials/question	A resource that provides functionality for changing the customer's security question.			REST API - Update 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 REST API - Delete product price notification B2C REST API - Update product price notification 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 REST API - Update private customer wish list REST API - Delete private customer wish list
/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.			REST API - Get wish list settings of private customer REST API - Update private customer wish list settings

4 Naming Convention and Practices

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