Page tree

      Frameworx Technical Report

 

Prepay Balance Management Enhancements 

API Conformance Profile

 

 

 

 

 

 

      TMF654C

      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:

4 Century Drive
Suite 100
P arsippany, 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

API Description

RESOURCE MODEL CONFORMANCE

Prepay Balance Management enhancements API MANDATORY AND OPTIONAL RESOURCES

BalanceReserve Resource MANDATORY AND OPTIONAL ATTRIBUTES

BalanceUnreserve Resource MANDATORY AND OPTIONAL ATTRIBUTES

BalanceDeduct Resource MANDATORY AND OPTIONAL ATTRIBUTES

BalanceDeductRollback Resource MANDATORY AND OPTIONAL ATTRIBUTES

NOTIFICATION MODEL CONFORMANCE

Prepay Balance Management enhancements API MANDATORY AND OPTIONAL NOTIFICATIONS

API OPERATIONS CONFORMANCE

Prepay Balance Management enhancements MANDATORY AND OPTIONAL OPERATIONS

API POST OPERATION CONFORMANCE

POST API/ balanceReserve

POST API/ balanceunReserve

POST API/ balancededuct

POST API/ balanceDeductRollback

Administrative Appendix

VERSION HISTORY

Release History

Acknowledgments

 

List of Tables

N/A

 

Introduction

This document describes the REST API Conformance for the Prepay Balance Management Enhancements API (TMF***)..

 

 

API Description

The Prepay Balance Management enhancements API covers some operations required to manage the balance of a prepay account, which includes balance reserve, unreserve, balance deduct and balance deduct rollback.

RESOURCE MODEL CONFORMANCE

Prepay Balance Management enhancements 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

BalanceReserve

M

 

BalanceUnreserve

M

 

BalanceDeduct

M

 

BalanceDeductRollback

M

 

 

BalanceReserve Resource MANDATORY AND OPTIONAL ATTRIBUTES

BalanceReserve Resource model is as following,

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 request messages)

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 request messages)

 

type

O

 

description

O

 

requestor

O

 

 

id

M (if requestor included)

O (otherwise)

 

 

href

M (in response messages and if  requestor included)

O (otherwise)

 

 

role

O

 

 

name

O

 

reservedAmount

M

 

remainedAmount

O

 

isAutoDeduct

O

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

requestedDate

O

 

confirmationDate

O

 

status

O

 

product

O

 

 

id

M (if product included)

O (otherwise)

 

 

href

M (in response messages and if product included)

O (otherwise)

 

partyAccount

O

 

 

id

M (if partyAccount included)

O (otherwise)

 

 

href

M (in response messages and if partyAccount included)

O (otherwise)

 

 

Type

O

 

relatedParty

O

 

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (in response messages and if relatedParty included)

O (otherwise)

 

 

N ame

O

 

 

Role

O

 

BalanceUnreserve Resource MANDATORY AND OPTIONAL ATTRIBUTES

 

Attribute Name

Mandatory / Optional

Comments

id

M(in request messages)

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 request messages)

 

description

O

 

requestor

O

 

 

id

M (if requestor included)

O (otherwise)

 

 

href

M (in response messages and if requestor included)

O (otherwise)

 

 

role

O

 

 

name

O

 

requestedDate

O

 

status

O

 

product

O

 

 

id

M (if product included)

O (otherwise)

 

 

href

M (in response messages and if product included)

O (otherwise)

 

relatedParty

O

 

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (in response messages and if relatedParty included)

O (otherwise)

 

 

N ame

O

 

 

Role

O

 

balance Reserve

M (in request messages)

 

 

id

M (if balance Reserve included)

O (otherwise)

 

 

href

M (in response messages and if balance Reserve included)

O (otherwise)

 

 

BalanceDeduct Resource MANDATORY AND OPTIONAL ATTRIBUTES

 

Attribute Name

Mandatory / Optional

Comments

id

M(in request messages)

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 request messages)

 

type

O

 

description

O

 

requestor

O

 

 

id

M (if requestor included)

O (otherwise)

 

 

href

M (in response messages and if requestor included)

O (otherwise)

 

 

role

O

 

 

name

O

 

requestedDate

O

 

confirmationDate

O

 

status

O

 

product

O

 

 

id

M (if product included)

O (otherwise)

 

 

href

M (in response messages and if product included)

O (otherwise)

 

partyAccount

O

 

 

id

M (if partyAccount included)

O (otherwise)

 

 

href

M (in response messages and if partyAccount included)

O (otherwise)

 

 

Type

O

 

relatedParty

O

 

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (in response messages and if relatedParty included)

O (otherwise)

 

 

N ame

O

 

 

Role

O

 

balancereserve

M (in request messages)

 

 

id

M (if balancereserve included)

O (otherwise)

 

 

href

M (in response messages and if balancereserve included)

O (otherwise)

 

 

BalanceDeductRollback Resource MANDATORY AND OPTIONAL ATTRIBUTES

Attribute Name

Mandatory / Optional

Comments

id

M(in request messages)

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 request messages)

 

description

O

 

requestor

O

 

 

id

M (if requestor included)

O (otherwise)

 

 

href

M (in response messages and if requestor included)

O (otherwise)

 

 

role

O

 

 

name

O

 

requestedDate

O

 

status

O

 

product

O

 

 

id

M (if product included)

O (otherwise)

 

 

href

M (in response messages and if product included)

O (otherwise)

 

partyAccount

O

 

 

id

M (if partyAccount included)

O (otherwise)

 

 

href

M (in response messages and if partyAccount included)

O (otherwise)

 

 

Type

O

 

relatedParty

O

 

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (in response messages and if relatedParty included)

O (otherwise)

 

 

N ame

O

 

 

Role

O

 

balanceDeduct

M (in request messages)O

 

 

id

M (if balanceDeduct included)

O (otherwise)

 

 

href

M (in response messages and if balanceDeduct included)

O (otherwise)

 

 

 

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.

 

Prepay Balance Management enhancements 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

BalanceReserveCreationNotification

O

 

BalanceUnreserveCreationNotification

O

 

BalanceDeductCreationNotification

O

 

BalanceDeductRollbackCreationNotification

O

 

 

 

 

  API OPERATIONS CONFORMANCE

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

Prepay Balance Management enhancements 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

O

GET must be used to retrieve a representation of a resource

 

POST

M

POST must be used to create a new resource

PATCH

O

PATCH must be used to partially update a resource

DELETE

O

DELETE must be used to remove a resource

 

 

 

 

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 API/ balanceReserve

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

The response to this operation must include a Location header set to / balanceReserve /{ID} where {ID} indicates the identifier assigned by the server to the new balanceReserve 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 balanceReserve 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

Default

Rule

id

M

 

 

href

M

 

 

type

O

 

 

description

O

 

 

requestor

O

 

 

reservedAmount

M

 

 

remainedAmount

O

 

 

isAutoDeduct

O

 

 

validFor

O

 

 

requestedDate

O

 

 

confirmationDate

O

 

 

status

O

 

 

product

O

 

 

partyAccount

O

 

 

relatedParty

O

 

 

 

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.

 

POST API/ balanceunReserve

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

The response to this operation must include a Location header set to / balanceUnreserve /{ID} where {ID} indicates the identifier assigned by the server to the new balanceUnreserve 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 balanceUnreserve 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

Default

Rule

id

M

 

 

href

M

 

 

description

O

 

 

requestor

O

 

 

requestedDate

O

 

 

status

O

 

 

product

O

 

 

relatedParty

O

 

 

balance Reserve

M

 

 

 

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.

 

POST API/ balancededuct

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

The response to this operation must include a Location header set to / balanceDeduct /{ID} where {ID} indicates the identifier assigned by the server to the new balanceDeduct 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 balanceDeduct 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

Default

Rule

id

M

 

 

href

M

 

 

type

O

 

 

description

O

 

 

requestor

O

 

 

requestedDate

O

 

 

confirmationDate

O

 

 

status

O

 

 

product

O

 

 

partyAccount

O

 

 

relatedParty

O

 

 

balancereserve

M

 

 

 

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.

 

POST API/ balanceDeductRollback

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

The response to this operation must include a Location header set to / balanceDeductRollback /{ID} where {ID} indicates the identifier assigned by the server to the new balanceDeductRollback 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 balanceDeductRollback 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

Default

Rule

id

M

 

 

href

M

 

 

description

O

 

 

requestor

O

 

 

requestedDate

O

 

 

status

O

 

 

product

O

 

 

partyAccount

O

 

 

relatedParty

O

 

 

balanceDeduct

M

 

 

 

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.


Administrative Appendix

VERSION HISTORY

Version Number

Date

Modified by

Description

Version 1.0.0

06/04/2017

Jiangtao Jia

jiajiangtao@huawei.com

Final version

 

 

 

 

 

Release History

Release Number

Date

Release led by:

Description

 

 

 

 

 

Acknowledgments

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