Document Properties
Kbid249M91
Last Modified24-Jun-2020
Added to KB12-Aug-2013
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Customer REST API

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

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

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

  • individual or household -> individual customer or
  • a business -> business customer.

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:

  • With single customer - simply put the user and customer are one thing
  • With group customer - an associate to an organization

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.

DIAG Customer REST API Applications and cartridges

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.

DIAG Customer REST API Applications

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).

Resource

Description

Requires authentication

Dynamic sub-resource

Reference

/customers/

A resource to provide functionality for customer's self registration.

(minus)

(minus)

REST API - Register SMB customer (until 7.7)

/customers/-/

A resource to provide functionality for retrieving customer's details.

(tick)

(minus)

REST API - Company profile details (until 7.8)
REST API - Update SMB customer profile (until 7.8)

/customers/-/addresses

A resource to provide functionality for customer's address management.

(tick)

(tick)

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.

(tick)

(tick)

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

A resources that allows viewing and updating of the profile details of currently logged in user of a business customer.

(tick)

(minus)

REST API - Profile details of user of a business customer (until 7.8)
REST API - Update profile of a customer's user (until 7.8)

/customers/-/users/-/credentials/passwordA resource to change business customer's user's password.

(tick)

(minus)

REST API - Update password of business customer's user
/customers/-/users/-/credentials/questionA resource to change business customer's user's security question

(tick)

(minus)

REST API - Update security question of business customer's user
customers/-/users/-/giftcardsandcertificatesA resource to view gift cards and certificates used or available by/to given user and check their balance.

(tick)

(tick)

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/stockA resource that allows management of product notification for availability.

(tick)

(tick)

REST API - Create product stock notification SMB

REST API - Update product stock notification SMB

REST API - Delete product stock notification SMB

REST API - Get product stock notification details SMB

/customers/-/users/-/notifications/priceA resource that allows management of product notification for reaching certain price threshold.

(tick)

(tick)

REST API - Get product price notification details SMB

REST API - Update product price notification SMB

REST API - Create product price notification SMB

REST API - Delete product price notification SMB

/customers/-/users/-/wishlistsA resource that allows management of user's wishlists.

(tick)

(tick)

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

REST API - Get business customer wish list details

REST API - Delete business customer wish list

/customers/-/users/-/wishlists/<wishlist-id>/shareA resource for sharing private wishlist with someone.

(tick)

(minus)

REST API - Share wish list of business customer's user with given recipient
/customers/-/users/-/wishlists/<wishlist-id>/settingsA resource for managing wishlist settings.

(tick)

(minus)

REST API - Get wish list settings of business customer

REST API - Update business customer wish list settings

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.

(minus)

(minus)

REST API - Create private customer (until 7.7)

/customers/-/

A resource to provide functionality for retrieving customer's details.

(tick)

(minus)

REST API - Update private customer profile (until 7.8)

/customers/-/addresses

A resource to provide functionality for customer's address management.

(tick)

(tick)

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.

(tick)

(tick)

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.

(tick)

(minus)

REST API - Update security question

/customers/-/credentials/passwordA resource to change business customer's password.(tick) (minus) REST API - Update password
/customers/-/credentials/questionA resource to change business customer's security question(tick)(minus)REST API - Update security question
customers/-/giftcardsandcertificatesA resource to view gift cards and certificates used or available by/to given customer and check their balance.(tick)(tick) 

REST API - Get the gift cards and certificates B2C

REST API - Get the balance of a specific gift card or certificate B2C

/customers/-/notifications/stockA resource that allows management of product notification for availability.(tick)(tick) 

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/priceA resource that allows management of product notification for reaching certain price threshold.(tick)(tick) 

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/-/wishlistsA resource that allows management of customer's wishlists.(tick)(tick)

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>/shareA resource for sharing private wishlist with someone.(tick)(minus)REST API - Share wish list of private customer with given recipient
/customers/-/wishlists/<wishlist-id>/settingsA resource for managing wishlist settings.

(tick)

(minus)

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

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.

Customer Support
Knowledge Base
Product Resources
Support Tickets