Page tree

 

 

 

 

 

 

 

Communication API
Conformance Profile

 

Document Number TMF681B

October 2017

 

 

 

 

 

 

 

Release: Frameworx Release 17.5

Status: 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
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

API Description

RESOURCE MODEL CONFORMANCE

Communication API MANDATORY AND OPTIONAL RESOURCES

Communication Message Resource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

Communication MANDATORY AND OPTIONAL OPERATIONS

API GET  OPERATION CONFORMANCE

GET / communicationMessage /{id} ?fields=...&{filtering}

API POST OPERATION CONFORMANCE

POST / communicationMessage

POST/communicationMessage/send

POST /communicationMessage/{id}/send

API PATCH OPERATION CONFORMANCE

PATCH /communicationMessage/{id}

API DELETE OPERATION CONFORMANCE

DELETE /communicationMessage/{id}

NOTIFICATION MODEL CONFORMANCE

Communication API MANDATORY AND OPTIONAL NOTIFICATIONS

Administrative Appendix

VERSION HISTORY

Release History

Acknowledgments

Contributors to Document

 

List of Tables

N/A

 

Introduction

This document describes the REST API Conformance for the Communication API .

 

 

API Description

This API provides a standardized mechanism for Communication management such as creation, update, retrieval, deletion and notification of the system communication events.

Communication API manages the following data resources:

-           Communication

  • Communication means the system delivers a message to the final customer in the form and format which can be felt and understood by the customer. The message can reach the customer in different interaction channels, including: email, short message, mobile app notification (push).

Normally the communication is implemented as a common shared service for all the enterprise IT applications. Whenever there is an application which needs to send the message to the customer, this application can invoke the “communication” API to dispatch the notification.

 

 

Communication API performs the following operation on the resource of “Communication Message”.

-           Retrieval of a n existing Communication Message depending on filter criteria

-           Creation of a new Communication message

-           Send a message, including:

  • Send a new message with the whole communication message body (POST operation)
  • Send a message with the predefined communication message body (POST operation)

-           Partial update of a n existing Communication Message

-           Deletion of a n existing Communication Message

-           Notification of events:

  • Creation of Communication Message
  • U pdat ing Communication Message
  • D elet ion of Communication Message

 

 

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 ( Communication ) 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

Communication 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

Communication Message

M

 

 

Communication Message 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.

 

Parameter

Mandatory/Optional

Comments

@type

O

 

@schemaLocation

O

 

@baseType

O

 

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

Priority

O

 

Type

M

 

Subject

O

 

Content

M

 

SendTime

O

 

sendTimeComplete

O

 

status

O

 

description

O

 

logFlag

O

 

callbackFlag

O

 

tryTimes

O

 

CommunicationRequestCharacteristic

O

List of parameters. (CommunicationRequestCharacteristic[*])

name

M

 

value

M

 

Sender

M

 

email

O

 

Id

O

 

name

O

 

phoneNumber

O

 

Receiver

M

List of receivers(Receiver[*])

appUserId

O

 

email

O

 

Id

o

 

Ip

O

 

Name

O

 

phoneNumber

O

 

RelatedParty

O

 

Id

M

 

Href

M

 

N ame

M

 

R ole

M

 

validFor

O

 

Attachment

 

List of attachments(Attachement[*])

name

M

 

Path

M

 

description

O

 

H ref

O

 

mimeType

O

 

size

O

 

sizeUnit

O

 

URL

O

 

validFor

O

 


 

API OPERATIONS CONFORMANCE

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

Communication 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

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

 

 

GET / communicationMessage /{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

 

The following table indicates attributes that are required to be sent

Note: “M” means mandatory, “O” means optional, “NA” means this attribute is not required.

Attribute name

Filtered search

First Level

Attribute Selection

First Level

Id

O

M

Href

NA

M

Priority

O

O

Type

O

O

Subject

O

O

Content

O

O

description

O

O

logFlag

O

O

callbackFlag

O

O

tryTimes

O

O

sendTimeComplete

O

O

SendTime

O

O

CommunicationRequestCharacteristic

NA

NA

Sender

O

O

Receiver

O

O

Attachment

NA

NA

 

 

 

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

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

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

Priority

O

Type

M

Subject

O

Content

M

SendTime

O

CommunicationRequestCharacteristic

O

Sender

M

Receiver

M

Attachment

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/communicationMessage/send

This operation is used to send a new Communication message from the “sender” to the “receiver”.

The response to this operation must include the status code to indicate whether the “sending” is successful or not.

 

POST

M

Status Code 20 0

M

Other Status Codes

NA

 

 

  The following table indicates attributes that are required to be sent when “sending” a new Communication 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

Priority

O

Type

M

Subject

O

Content

M

SendTime

O

CommunicationRequestCharacteristic

O

Sender

M

Receiver

M

Attachment

O

 

POST /communicationMessage/{id}/send

This operation is used to send a pre-defined c ommunication message from the “sender” to the “receiver”.  In this mode, the message body should be created in advance. The “Communication Message Creation” needs to be invoked firstly, so the system can send the pre-defined message.

The response to this operation must include the status code to indicate whether the “sending” is successful or not.

 

POST

M

Status Code 20 0

M

Other Status Codes

NA

 

The request needs to contain the ID of an existing communication message.

Attribute name

Mandatory /Option

id

M

 

API PATCH OPERATION CONFORMANCE

 

PATCH /communicationMessage/{id}

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

 

PATCH

O

THIS PATCH OPERATION

Status Code 20 0

M

 

Other Status Codes

NA

 

 

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

Attribute name

P atchable

id

N

href

N

Priority

Y

sendTimeComplete

Y

status

Y

description

Y

logFlag

Y

callbackFlag

Y

tryTimes

Y

Type

N

Subject

Y

Content

Y

SendTime

Y

CommunicationRequestCharacteristic

Y

Sender

Y

Receiver

Y

Attachment

Y

 

 

API DELETE OPERATION CONFORMANCE

 

DELETE /communicationMessage/{id}

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

For this operation, only the “ 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.

 

Communication 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

CommunicationMessageCreationNotification

O

.

 

CommunicationMessageDeletionNotification

O

 

CommunicationMessageUpdateNotification

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

initial version

 

6 /14/2017

 

Updated version

 

9/10/2017

Hongxia Hao

haohongxia @huawei.com

Ma Xu

Maxu@huawei.com

 

Align with the newest specification document

 

Release History

Release Number

Date

Release led by:

Description

 

 

 

 

 

Acknowledgments

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

Contributors to Document

Name

Company

Ma Xu

Huawei

Hongxia Hao

Huawei

Sophie Bouleau

Orange

Pierre Gauthier

TM Forum