Page tree

      Frameworx Technical Report

 

Promotion

API Conformance Profile

 

 

 

 

 

 

      TMF***

      Release 1 7

      February 201 7

         

 

 

 

Latest Update: Frameworx Release 17

Member Evaluation

Version 1.0.1

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:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 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

API Description

RESOURCE MODEL CONFORMANCE

Promotion API MANDATORY AND OPTIONAL RESOURCES

Promotion Resource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

Promotion MANDATORY AND OPTIONAL OPERATIONS

API GET  OPERATION CONFORMANCE

Filtering GET / promotion /{ID} ?fields=...&{filtering}

API POST OPERATION CONFORMANCE

POST /promotion

API PATCH OPERATION CONFORMANCE

PATCH Promotion/{ID}

API DELETE OPERATION CONFORMANCE

DELETE Promotion/{ID}

NOTIFICATION MODEL CONFORMANCE

Promotion API MANDATORY AND OPTIONAL NOTIFICATIONS

Administrative Appendix

VERSION HISTORY

Release History

Acknowledgments

 

List of Tables

N/A

 

Introduction

This document describes the REST API Conformance for the Promotion API ( TMF** [m01] *)..

 

 

API Description

The Promotion API provides the standardized client interface to Promotion for creating, tracking and managing the promotion which is used to provide the online e-commerce incentive for the customer according to the pre-configured criteria. The instances of Promotion Activity API originators (clients) include CRM applications especially the online channels (e.g. mobile app).

A promotion represents a record used to express the configuration of simulation policy for the online shopping.

The operations that can be exercised over a promotion resource using the API and covered in this document are those identified as mandatory to be supported such as

 

 

This document identifies the parameters that must be included in a request related to the operations above as well as the parameters expected in the response.

 

The test scenarios in this document are intended to create a set of resources ( Promotion ) and then retrieve the information stored in the server so as to confirm the resources created are stored with the values originally set. Additionally, some test scenarios are included to verify that the server replies with the corresponding error response in situations where a mandatory attribute is not included in the request.

 

 

RESOURCE MODEL CONFORMANCE

Promotion API MANDATORY AND OPTIONAL RESOURCES

For the Resources defined by the API, here the following table indicates which are mandatory and which ones are optional.

 

Resource Name

Mandatory / Optional

Comments

Promotion

M

 

 

Promotion Resource MANDATORY AND OPTIONAL ATTRIBUTES

For every single resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

Attribute Name

Mandatory / Optional

Comments

id

M (in response messages)

O (otherwise)

Generated by the server and provided in the response upon resource creation.

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources.

href

M (in response messages)

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

name

M

 

priority

O

 

type

O M

 

d D escription

O

 

lifecycleStatus

O

Its  default value is Draft .

validFor

O

 

lastUpdate

O

 

p romotion TargetItem

O

A list of promotion tar g et items. (P romotion TargetItem[*])

 

itemType

M

 

 

itemI d

M

 

p romotion Pattern

O

A list of  promotion patterns. (P romotion Pattern[*])

 

id

O

 

 

name

M

 

 

priority

O

 

 

relationTypeAmongGroup

O M

 

 

d D escription

O

 

 

p romotion C riteria Group

O

A list of p romotion c riteria groups. ( PromotionCriteria Group[*])

 

i d

M

 

 

groupName

M

 

 

relationTypeInGroup

M

 

 

p romotionCriteria

O

A list of p romotion c riteria s. (  P romotionCriteria [*])

 

 

id

M

 

 

 

criteriaPara

M

 

 

 

criteriaValue

M

 

 

 

criteriaOperator

M

 

 

p romotion A ction

O

A list of promotion actions.(PromotionAction[*])

 

i I d

M

 

 

action Type

M

 

 

action Value

M

 

 

action Object Id

M

 

 

operationObjectId

M

 

p romotion Specification

O

 

 

id  

M

 

 

href

M

 

 

name

O

 

 

lastUpdate

O

 

 

lifecycleStatus

O

 

 

valideFor

O

 

 

API OPERATIONS CONFORMANCE

For every single resource, here use the following templates to define what operations are optional and what operations are mandatory.

Promotion MANDATORY AND OPTIONAL OPERATIONS

Fill the following table and indicate which ones are mandatory and which ones are optional.

 

Uniform API Operation

Mandatory/Optional

Comments

GET (Retrieve)

M

GET must be used to retrieve a representation of a resource

 

POST

M

POST must be used to create a new resource

GET (List)

O

GET must be used to retrieve  the representation of a set of resource

PATCH

O

PATCH must be used to partially update a resource

DELETE

O

DELETE must be used to remove a resource

 

API GET  OPERATION CONFORMANCE

 

For every single resource, use the following template to specify the mandatory and optional features supported by the GET operation.

GET

O

THIS PATCH OPERATION

Status Code 20 0

M

 

Other Status Codes

NA

 

 

Filtering GET / promotion /{ID} ? fields=...&{filtering}

 

Definitions

Filtered Search :

A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search. In that case logic, a logical AND is applied to combine the criteria (e.g.:?severity=<value> &status=<value>)

Filtered Data (Attribute selection):

In order to apply a filter and limit the number of attributes included in the response, the GET request can include the “?fields=” query parameter. Several elements can be applied to the filter. In that case, a logical AND is applied to combine the values (e.g.:?fields=severity,status) will provide in the response only the values assigned to attributes category and channel. Attribute selection capabilities are the same for collections retrieval and individual resource queries

 

Attribute name

Filtered search

First Level

Attribute Selection

First Level

d D escription

O

O

lastUpdate

O

O

lifecycleStatus

O

O

name

O

M

valideFor

O

O

id

O

M

href

NA

M

p romotion Pattern

O

O

p romotion TargetItem

O

O

 

 

API POST OPERATION CONFORMANCE

 

For every single resource, use the following template to specify the mandatory and optional features supported by the POST operation.

 

POST / promotion

This operation is used to create a managed entity for Promotion.

The response to this operation must include a Location header set to /promotion/{ID} where {ID} indicates the identifier assigned by the server to the new Promotion resource created:

 

POST

M

 

Status Code 201

M

 

Other Status Codes

NA

 

 

 

  The following table indicates attributes that are required to be sent when creating a new Promotion resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as a part of the BODY of the POST request message.

Attribute name

Mandatory /Option

Default

Rule

d D escription

O

 

 

lastUpdate

O

 

 

lifecycleStatus

O

 

 

name

M

 

 

valideFor

O

 

 

type

M O

 

 

promotionTargetItem

O

 

 

p romotion Pattern

O

 

 

promotionSpecification

 

 

 

 

The response from the server must include a BODY with the contents of the new resource created, filled with at least the same information elements that are included in the request and are supported by the server.

If the POST request includes optional parameters (as per the model resource definition) that are not supported by the server, then the server must reject the request (replying with a 4xx error response) indicating the parameter not supported.

API PATCH OPERATION CONFORMANCE

 

PATCH Promotion/{ID}

This patch operation is used to partially update the representation of a managed entity for Promotion .

 

PATCH

O

THIS PATCH OPERATION

Status Code 20 0 1

M

 

Other Status Codes

NA

 

 

       The mandatory and optional attributes of the API are same as the following:

Attribute name

P atchable

Default

Rule

d D escription

Y

 

 

lastUpdate

Y

 

 

lifecycleStatus

Y

 

 

name

Y

 

 

valideFor

Y

 

 

type

Y

 

 

p romotion P attern

Y

 

 

p romotion TargetItem

Y

 

 

p romotion Specification

Y

 

 

 

 

API DELETE OPERATION CONFORMANCE

 

DELETE Promotion/{ID}

This operation is used to remove the representation of a managed entity for Promotion.

For this operation, only the “ id ID ” field is mandatory for the client of the API. All other fields are not required.

DELETE

O

THIS PATCH OPERATION

Status Code 20 0

M

 

Other Status Codes

NA

 

 

 

 

NOTIFICATION MODEL CONFORMANCE

 

The Pub/Sub models are common and described in the TMF REST Design Guidelines. Use the following templates to describe the Hub Mandatory and Optional attributes and filtering support.

 

Promotion API MANDATORY AND OPTIONAL NOTIFICATIONS

For the Notifications defined by the API, it is filled in the following table to indicate which ones are mandatory and which ones are optional.

All notifications are optional.

 

Resource Name

Mandatory or Optional

Comments

Promotion CreationNotification

O

.

 

Promotion ChangeNotification

O

 

 

 


Administrative Appendix

VERSION HISTORY

Version Number

Date

Modified by

Description

Version 1.0.0

8/0 5 /2017

Ma Xu

Maxu@huawei.com

Hongxia Hao

haohongxia @huawei.com

Final initial   version

 

6 /14 /2017

 

U pdated version

 

Release History

Release Number

Date

Release led by:

Description

 

 

 

 

 

Acknowledgments

This document was reviewed by members of the TM Forum API Program team.

 


[m01] To be changed when Promotion API is published.