Page tree

 

 

 

 

 

 

 

Recommendation
API REST Specification

 

Document Number TMF680

July 2017

 

 

 

 

 

 

 

Release: Frameworx Release 17.5

Status: Member Evaluation

Version: 1.0.0

IPR Mode: RAND

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

 

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

4 Century Drive
Suite 100
Parsippany, NJ 07054, USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

Mapping with SID ABE

Mapping with Business Process Framework (eTOM)

Difference between Recommendation API and other existing TMF APIs

SAMPLE USE CASES

RESOURCE MODEL

Managed Entity and Task Resource Models

Recommendation Resource

API OPERATION TEMPLATES

Get Recommendation

Acknowledgements

Release History

Contributors to Document

List of Tables

 

N/A

 

Introduction

The following document is the specification of the REST API for Recommendation . It includes the model definition as well as all available operations.

 

It provides a standardized mechanism for recommendation management such as creation, update, retrieval, deletion and notification of events.

Recommendation API manages the following data resources:

-           Recommendation

  • Recommendation is a type of automated (typically, conditional) system action to determine which products offerings to be presented as up-sells, cross-sells, and related products to each customer segment based on customer and session specific information. The design-time offers and product recommendations may come from Marketing and Catalog. The run-time evaluation and presentment will be executed with contextual/session information. Normally, it supports the recommendation of the offer which is proper for the customer, provides Up-sell and cross-sell based on contextual and catalog rules.

 

Recommendation API is used to recommend offering quickly based on the history and real-time context of customer. It is a real-time and personalized recommendation API. It is usually provided by e-commerce or BSS, CRM system in omni-channel.

 

The typical example of recommendation is on the online e-commerce site.

 

Mapping with SID ABE

Recommendation is related to“ Product Domain::Product Offering ABE ” in TMF Information Framework (SID).

 

Mapping with Business Process Framework (eTOM)

In Business Process Framework there is the description for promotion:

         Level 2 Process: 1. 1.9 Selling

         Lev el 3 Process: 1. 1.9.3 Cross/Up Selling

         Level 4 Process : 1. 1.9.3.2 Recommend Appropriate Offerings

The description of “ Recommend Appropriate Offerings ” is to recommend the appropriate offering to the customer. It is the important approach to attract the customer and propel more revenue increase.

 

 

Difference between Recommendation API and other existing TMF APIs

Here the differences between Recommendation API and other existing published TMF APIs are explained to clarify why this separate API is not covered simply with those APIs.

         Difference with Product Catalog API

Recommendation and Product Offering in the Product Catalog has some similarities. The product offering is the object which is recommended to the customer.

Product Catalog API focuses on the configuration of product offering. When querying with Product Catalog API, all the existing offerings will be included in the query result. Instead, recommendation API only fetches the offerings which possibly cause the interest of the customer.

 

         Difference with   Product Offering Qualification API

Product Offering Qualification acquires the validated and available product offering for the customer to purchase. These offerings are all the allowed options for the customer.

Recommendation API provides the most possibly-chosen offering for the customer.  Such offerings are selected for the customer as the first and primary choice, not only the normal sellable objects.

 

         Difference with Shopping Cart API

The Shopping Cart API is a container to load the selected offerings for the customer to purchase. It does not replace the recommendation.

The recommendation often accompanies with the shopping cart. Based on the selected offerings in the cart, the recommended offerings are shown nearby. But the recommendation is not done by the shopping cart itself.

 

 

SAMPLE USE CASES

E xamples of use cases using Recommendation API is as following

 

cid:image001.png@01D341D8.761E1260

RESOURCE MODEL

Managed Entity and Task Resource Models

 

Recommendation Resource

Recommendation Resource Model:

 

 

 

Recommendation Resouce

 

Parameter

Data Type

Description

@type

String

It indicates the class type of the catalog.

@schemaLocation

String

It provides the link to the schema describing REST resource

@baseType

String

It indicates the base type of REST resource.

description

String

Description of recommendation

i d

String

Unique identifier of recommendation

h ref

String

Hypertext Reference of the recommendation .

name

String

Name of recommendation

validFor

TimePeriod

The period in which the recommendation is valid.

type

String

Category of recommendation.

The basic type is :

‘AD’: it means the recommendation is the advertisement for display

‘OFFER’: it means the recommended content is the offer entry page. By clicking it, the user can be forwarded to the details of the offering

recommendationItem

 

A list of recommendation items. Every item is a product offering and its priority .

priority

Integer

Priority level for applying this alteration among all the defined alterations .

 

productOffering

 

ProductOfferingRef (P roductOfferingRef )Recommended Product offering

 

id

String

Unique identifier of product offering

 

href

String

Hypertext Reference of the product offering .

 

name

String

N ame of the product offering.

category

 

Category (CategoryRef), Different kinds of recommendation. For example, it can be used to describe different recommendation positions on the e-commerce web site.

id

String

Unique identifier of category

href

String

Hypertext Reference of the category .

name

String

N ame of the category.

Channel

 

Channel(ChannelRef) The channel where the recommendation is used. M ay be online web, mobile app, social ,etc .

Id

String

Unique identifier of channel

href

String

Hypertext Reference of the channel .

name

String

N ame of the channel.

S hoppingCart

 

S hoppingCart (S hoppingCart Ref) . The shopping cart which the recommendation is related with.

Id

String

Unique identifier of shopping cart

href

String

Hypertext Reference of the shopping cart .

ProductOrder

 

ProductOrder (ProductOrder) . The product order which the recommendation is related with.

Id

String

Unique identifier of product order

href

String

Hypertext Reference of the product order .

GeographicLocation

 

GeographicLocation (GeographicLocationRef) The geographic location which the recommendation is related with.

Id

String

Unique identifier of geographic location

href

String

Hypertext Reference of the geographic location.

name

String

N ame of the geographic location .

type

String

Type of the geographic location .

relatedParty

 

relatedParty ( relatedParty Ref). The party which the recommendation is related with.

Id

String

Unique identifier of related party

href

String

Hypertext Reference of the related party.

name

String

N ame of the related party .

role

String

Role of the related party .

 

Recommendation Sample

 

{

             “id”:”1001”,

             “href”:"http://serverlocation:port/recommendation /v1/ recommendation/1001",

“name”:” recommendation of the latest Apple iPhone” ,

"description": " recommendation of the latest Apple iPhone for the customer with high revenue contribution",

"@type": "recommendation",

"@schemaLocation":"http://serverlocation:port/recommendation/schema/ recommendation.yml",

"@baseType": "",

“recommendationI tem ”: [

{

“priority”:1,

“productOffering”:

{

                "href": "https://host:port/productOffering/ v1/ productOffering s/ 6547",

                "id": "6547",

                "name": "phone1"

}

},

{

“priority”:2,

“productOffering”:

{

                "href": "https://host:port/productOffering/ v1/ productOffering s/ 6547",

                "id": "6542",

                "name": " phone2"

}

}

],

  "validFor": {

                       "startDateTime": "2017-12-19 T04:00:00.0Z",

                      "endDateTime": "2017-12-31 T20:42:23.0Z"

},

“type”: “OFFER”,

"channel":

{

"id": "13",

"href": "http://serverlocation:port/recommendation /v1/ channel /13",

              “name”: “mobile app channel”

},

"relatedPart y ":

{

    "id": "34",

“href": "http://serverlocation:port/partyManagement /v1 /individual/34",

  “name”: “John Smith”,

                 "role": “”

}

“geographicLocation”:{

“id”:”334”

}

}

 

 

 

API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST requests and responses.

Remember that the following Uniform Contract rules must be used:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

 

 

 

 

 

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

 

Get Recommendation

GET /recommendation?fields= &{filtering}

Description:

         This operation is used to query r ecommendations by query conditions

         This operation is usually used by e-commerce client. When the client query recommendation , it will trigger the server to generate the recommendation quickly by Big Data analysis tech.  or AI, Machine Learning tech. The server will response with the recommendation result.

         Attribute selection is enabled for all first level attributes.

         Attribute Filtering may be available depending on the compliance level supported by an implementation.

F or example :

1.Get recommendions by relatedParty id and channel id

  GET  /recommendation ? relatedParty. id =VALUE & channel. id= VALUE     

2.Get recommendions by relatedParty id , channel id and  shoppingcart id.  Usually, we need to recommend specific offering when the customer change his shopping cart.

GET  /recommendation? relatedParty. id =VALUE&shoppingCart.id=120

3.Get recommendions by relatedParty id , channel id and  location id. Usually, we need to recommend specific offering when the customer’s location changes.

GET  /recommendation? relatedParty. id =VALUE& geographicLocation.id=120

 

Usage Samples

Here's an example of a request for retrieving R ecommendation resources.

REQUEST

GET /recommendation? relatedParty.id= 10023 & channel.id= 2053

Content-type: application/json

Accept: application/json

RESPONSE

 

{

“id”:”1001”,

“href”:"http://serverlocation:port/recommendation /v1/ recommendation/1001",

“name”:” recommendation of the latest Apple iPhone” ,

"description": " recommendation of the latest Apple iPhone for the customer with high revenue contribution",

"@type": "recommendation",

"@schemaLocation":"http://serverlocation:port/recommendation/schema/ recommendation.yml",

"@baseType": "",

“recommendationItem”: [

{

“priority”:1,

“productOffering”:

{

                “href”: “https://host:port/productOffering/ v1/ productOffering s/ 6547”,

                “id”: “6547”,

                “name”: “phone1”

}

},

{

“priority”:2,

“productOffering”:

{

                “href”: “https://host:port/productOffering/ v1/ productOffering s/ 6547”,

                “id”: “6542”,

                “name”: “ phone2”

}

}

],

“validFor”: {

         “startDateTime”: “2017-10-9 T04:00:00.0Z”,

         “endDateTime”: “2017-10-9 T20:42:23.0Z”

},

“type”: “OFFER”,

“channel”: {

“id”: “2503”,

“href”: “http://serverlocation:port/recommendation /v1/ channel/13”,

           “name”: “mobile app channel”

},

“relatedPart y ”: {

“id”: “10023”,

“href”: “http://serverlocation:port/partyManagement /v1 /individual/34”,

           “name”: “John Smith”,

“role”: “”

}

}

Acknowledgements

Release History

Release Number

Date

Release led by:

Description

Release 0.1

31/0 5 /2017

 

First Release of Draft Version of the Document.

Release 0.12

12 /0 7 /2017

 

U pdate by Hongxia

1.0.0

9 /10/2017

 

Address the comments from orange. , Merge the etiya’s contribution.

1 .0.1

30/10/2017

 

Address the comments from amdocs . ,

 

Contributors to Document

 

  • MaXu, Huawei

maxu@huawei.com

  • Hongxia Hao , Huawei

haohongxia @huawei.com

Initial version

  • MaXu, Huawei

maxu@huawei.com

  • Hongxia Hao , Huawei

haohongxia @huawei.com

  • Lu dovic Robert

ludovic.robert@orange.com

  • Serafettin ACIR

serafettin.acir@etiya.com

Add some related information