Page tree

 

 

 

 

 

 

 

Usage Consumption API
REST Specification

 

Document Number TMF677

September 2017

 

 

 

 

 

 

 

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

SAMPLE USE CASES

RESOURCE model

Managed Entity and Task Resource Models

usage consumption report resource

usage consumption report request resource

Notification Resource Models

usage consumption report request State Change Notification

API OPERATIONS

Operations on usage consumption report

Query an usage consumption report in synchronous mode

Retrieve usage consumption report

Create usage consumption report

Delete usage consumption report

Operations on usage consumption report Request

create an usage consumption report request

LIst usage consumption report requests

retrieve usage consumption report request

Delete usage consumption report request

API NOTIFICATIONS

Register listener

Unregister listener

Publish Event to listener

Acknowledgements

Release History

List of Tables

N/A

 

Introduction

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

This API covers the consumption follow up function providing ongoing information about usages related to any subscribed communication products (voice, data, TV,…) without having to wait the invoice production. These information may concern usages charged on a bucket supervised or not and so the remaining credits on the bucket. It allows customers or users to be informed on usages done and remaining credits on the buckets that they consume under their purchased offers and options.

A bucket is a quantity of units (time, volume, currency or events) available via a subscribed offer or option and that can be consumed during a validity period. A bucket has at least one balance valid at a given point. This balance is decremented by usage charged on the bucket and incremented by credit operations (like top-up operations for example). At a given point, this balance defines the remaining allowed usage quantity for a given period, corresponding to the initial allowed usage quantity minus consumed usage quantity.

The bucket has also consumption counters which give measures about the usage quantity consumed on the bucket. These counters can be detailed by device or by user for example when a bucket is shared between several devices or several users.

The usage consumption API allow to view at a given point the balance and the consumption counters of the various buckets (SMS, Voice, Data for example) that one or more user(s) consume with each of his devices, according to the purchased offers and options.

An usage consumption report retrieves the data related to these balances and various consumption counters and calculated at the time of the request by the server.

So the API allows to r etrieve usage consumption report with information about balances and consumption counters for a given criteria : subscribed offer or option, a given device or an user for example.

The use of the both resources described in this document is conditioned by the capability of the server.

  • If the server could perform the calculation and so give the usage consumption report in synchronous mode according to the criteria given by the API requester, a GET operation with filter criteria on usageConsumptionReport resource could be used. We could accept to use a GET operation in this context because the server calculates the data given in the usage consumption report without necessarily store it.
  • We must also anticipate the use case where the server could only give an asynchronous response to the calculation of an usage consumption report requested by the API requester. In this case, a POST operation on usageConsumptionReportRequest could be sent by the API Requester asking the server that a usage consumption report calculation has to be performed. Then, the API requester could follow the process with a GET operation on this same resource retrieving the status of the request. The server could also use the notification pattern to inform the API requester that the usage consumption report is available.

 

SAMPLE USE CASES

To illustrate JSON representation of resources concerned by these APIs, we use the three use cases detailed below.

Use case 1 (UC1) : one user Kate with one device

Kate has a smartphone identified by msisdn number 0601010101. She subscribed to a MainOffer allowing her to consume three monthly buckets : a national voice bucket with an initial value of 2 hours, a SMS bucket with an initial value of 120 SMS and a data bucket with an initial value of 3 Go. She also subscribed to an option CanadaUSAPass with a Canada/USA voice bucket with an initial value of 30 minutes and a SMS bucket with an initial value of 10 SMS.

With her smartphone, Kate has used 40 minutes on the national voice bucket, 25 sms on sms bucket and 1.2 Go on the data bucket of the main offer. She also has consumed 20 minutes on the voice bucket and 10 sms ont the sms bucket of the Canada/USA Pass.

Use case 2 (UC2) : one user Lea with two devices consuming a shared data bucket

Lea has two devices : a smartphone identified by msisdn number 0602020202 and a phablet identified by msisdn number 0603030303. She subscribed to a MainOffer allowing her to consume with its smartphone two monthly buckets : a national voice bucket with an initial value of 2 hours and an unlimited SMS bucket. She also subscribed to a Shared Data offer with an initial value of 5 Go. This data bucket is shared with the phablet et can also be consumed by it.

With her smartphone, Lea has used 60 minutes on the voice bucket, 123 sms on the SMS bucket and 1.0 Go on the 3.0 Go used in the data shared bucket. She also has used 2.0 Go with the phablet on the 3.0 Go used in the data shared bucket.

Use case 3 (UC3) : a shared data bucket consumed by a community of two users

Kate is the contract holder. Kate subscribes to a Shared Data offer containing a shared data bucket of 5 Go consumed by a community (family) of two users : Kate and Lea. Kate consumes it with her smartphone identified by msisdn number 0601010101 and Lea with her smartphone identified by msisdn number 0602020202 and her tablet identified by msisdn number 0603030303.

Lea has used 1 Go with her smartphone and 1.2 Go with the phablet. Kate has used 1.0 Go with her smartphone.

RESOURCE model

Managed Entity and Task Resource Models

usage consumption report resource

An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). It could be calculated for a device identified by a public identifier (msisdn number for a mobile device for example or PSTN or VOIP number for a fix device), for a subscribed offer or option or for an user.

A bucket could be shared between several devices and/or several users. It has static characteristics and dynamic characteristics (balances with remaining value and consumption counters like consumed value for example). If the bucket is shared between several network products, the used value is given globally for all network products and detailed for the network product for which the usage report is given.

Nota : A FixedQuantityPackageProdSpec entity, representing a quantity of usage, is defined as an example of ProductSpecification on SID document GB922 related to Product. This entity is instantiated as a FixedQuantityPackageProduct entity in the customer installed base. This entity is renamed in bucket on the API Data model to be better understood.

Resource model

Lifecycle

No lifecycle for this resource.
 

Field descriptions

UsageConsumptionReport

id

A string. Unique identifier of the usage consumption report given by the server.

href

A string. Hyperlink to access the usage consumption report.

name

A string. Usage consumption report name.

description

A string. Free short text describing the usage consumption report content.

effectiveDate

A date time (DateTime). Date and time when the usage consumption report was calculated and generated.

relatedParty

A related party (RelatedPartyRef). Reference of the party for which the usage consumption report is produced.

bucket

A list of buckets (Bucket[*]). Bucket included in the offer or option subscribed.

Bucket

A bucket represents a quantity of usage, as 2 hours national calls or 50 sms for example. It could be either a quantity or an amount in a currency (i.e. It could represent a fixed number of SMS, MMS, minutes of calls, quantity of data, number of events as well as a specific amount in a given currency). It requires one or more network products from which usages will debit the bucket.

id

A string. Unique identifier of the bucket.

name

A string. Bucket name.

usageType

A string. Type of usage concerned by the bucket (voice, sms, data,…).

isShared

A boolean. True if the bucket is shared between several devices or users.

product

A product reference (Product). Offer or option through the bucker is subscribed.

bucketBalance

A list of bucket balances (Balance[*]). Balance of the bucket that can be given in various units.

bucketCounter

A list of bucket counters (ConsumptionCounter[*]). Counters detailing usage consumption on the bucket.

 


Product

An instantiated product corresponding to a simple product offering subscribed by a customer.

id

A string. Unique identifier of the product.

href

A string. Reference of the product.

name

A string. Product name.

publicIdentifier

A string. Public number associated to the product (msisdn number for mobile line for example)

user

An user (RelatedPartyRef). Reference of the user of the product.

Balance

The balance defines the remaining allowed product usage quantity in terms of volume, time, currency or events. It corresponds to the initial allowed usage quantity minus the usage consumed on the bucket.

unit

A string. Code of the unit used to specify the given value of the balance. It could be different from the bucket unit.

remainingValue

A number. Numeric remaining value for the bucket given in the balance unit (for example 1.9). This numeric value could be used for calculation for example.

remainingValueLabel

A string. Remaining value in a formatted string for the bucket given in the balance unit (for example 1.9 Gb). This formatted string could be used for display needs for example.

validFor

A time period (TimePeriod). Balance period between a start date time and an end date time. For prepaid bucket, the period of the balance is between the  effective date of the usage consumption report generation and the end date of the bucket.   For postpaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the next bill date.

ConsumptionCounter

The consumption counters detail for example the different kind of consumption done on the bucket.

counterType

A string. Type of the consumption counter. We can give for example a counter of the used value.

level

A string. Counter level. The given counter can be given globally for the bucket or detailed by user or by product for example in case of shared bucket.

unit

A string. Unit of the counter.

value

A number. Numeric value of the bucket counter in the given unit.

valueLabel

A string. Value of the counter in a formatted string used for display needs for example.

validFor

A time period (TimePeriod). Consumption counter period between a start date time and an end date time. For prepaid bucket, the period of counters is between the start date of the bucket and the effective date of the usage consumption report generation. For postpaid bucket, the period of counters is between the last bill date and the effective date of the usage consumption report generation.

product

A product (Product). Public number associated to the product for which the consumption counter is detailed.

user

An user (RelatedPartyRef). Reference of the user for which the consumption counter is detailed.

RelatedPartyRef

Related party reference.

id

A string. Unique identifier of a related party.

href

A string. Reference of the related party, could be a party reference or a party role reference.

name

A string. Name of the related party.

role

A string. Role of the related party.

Json representation sample

We provide below the json representation of a sample of a “UsageConsumptionReport” resource object corresponding to the use case 1 (one usage report for product identified by public identifier 0601010101 used by the user Kate which consumes five buckets) :

{

    "id": "ucr0001",

    "href": "https://host:port/usageManagement/usageConsumptionReport/ucr0001",

    "name": "Usage consumption report ucr0001",

    "description": "Usage  consumption Report for Kate smartphone",

    "effectiveDate": "2016-03-15T:15:44:28",

    "bucket": [

        {

            "id": "bkt001",

            "name": "main offer data",

            "usageType": "data",

            "isShared": "false",

            "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                    "publicIdentifier": "33601010101",

                    "user": {

                        "id": "usr1",

                        "name": "Kate",

                        "role": "user"

                    }

                 },

           "bucketBalance": [

               {

                  "unit":"Go",

                  "remainingValue": 1.8,

                  "remainingValueLabel": "it remains 1.8 Go",

                  "validFor": {

                         "startDateTime": "2016-03-15T:00:00:00",

                         "endDateTime": "2016-03-30T:00:00:00"

                   }

               }

           ], 

           "bucketCounter": [

              {

                    "counterType":"used",

                    "level":"global",

                    "unit":"Go",

                    "value": 1.2,

                    "valueLabel": "1.2 Go used",

                  "validFor": {

                         "startDateTime": "2016-03-01T:00:00:00",

                         "endDateTime": "2016-03-15T:00:00:00"

                   }

                }

            ]

         },

        {

             "id": "bkt002",

             "name": "main offer national voice",

             "usageType": "national voice",

             "isShared": "false",

              "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                    "publicIdentifier": "33601010101"

                    "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

               },

              "bucketBalance": [

                   {

                       "unit":"mins",

                        "remainingValue": 80.0,

                       "remainingValueLabel": "it remains 80 minutes",

                       "validFor": {

                            "startDateTime": "2016-03-15T:00:00:00",

                            "endDateTime": "2016-03-30T:00:00:00"

                       }

                   }

              ], 

              "bucketCounter": [

                   {

                       "counterType":"used",

                       "level":"global",

                       "unit":"mins",

                       "value": 40.0,

                       "valueLabel": "40 mins used",

                       "validFor": {

                            "startDateTime": "2016-03-01T:00:00:00",

                            "endDateTime": "2016-03-15T:00:00:00"

                       }

                   }

             ]

         },

        {

              "id": "bkt003",

              "name": "main offer sms",

              "usageType": "sms",

              "isShared": "false",

                "product":  {

                     "id": "product1",

                      "name": "Main Offer",

                      "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

                 },

                "bucketBalance": [

                     {

                          "unit":"sms",

                          "remainingValue": 95.0,

                          "remainingValueLabel": "it remains 95 sms",

                          "validFor": {

                              "startDateTime": "2016-03-15T:00:00:00",

                              "endDateTime": "2016-03-30T:00:00:00"

                          }

                     }

                 ], 

                "bucketCounter": [

                     {

                        "counterType":"used",

                        "level":"global",

                        "unit":"sms",

                        "value": 25.0,

                        "valueLabel": "25 sms used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                        }

                     }

                ]

            },

            {

                 "id": "bkt004",

                 "name": "option Canada/USA voice",

                 "usageType": "Canada/USA voice",

                 "isShared": "false",

                 "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                       "user": {

                             "id": "usr1",

                              "name": "Kate",

                              "role": "user"

                        }

                      },

                     "bucketBalance": [

                         {

                             "unit":"mins",

                             "remainingValue": 10.0,

                             "remainingValueLabel": "it remains 10 minutes",

                             "validFor": {

                                 "startDateTime": "2016-03-15T:00:00:00",

                                 "endDateTime": "2016-03-30T:00:00:00"

                             }

                        }

                     ], 

                     "bucketCounter": [

                         {

                               "counterType":"used",

                               "level":"global",

                               "unit":"mins",

                               "value": 20.0,

                               "valueLabel": "20 mins used",

                               "validFor": {

                                    "startDateTime": "2016-03-01T:00:00:00",

                                    "endDateTime": "2016-03-15T:00:00:00"

                                }

                        } 

                    ]

               },

               {

                   "id": "bkt005",

                   "name": " Canada/USA sms",

                   "usageType": "sms",

                   "isShared": "false",

                   "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                            "name": "Kate",

                            "role": "user"

                         }

                      },

                   "bucketBalance": [

                        {

                            "unit":"sms",

                            "remainingValue": 0.0,

                            "remainingValueLabel": "Sms bucket exhausted",

                             "validFor": {

                                 "startDateTime": "2016-03-15T:00:00:00",

                                 "endDateTime": "2016-03-30T:00:00:00"

                             }

                        }

                     ], 

                     "bucketCounter": [

                         {

                              "counterType":"used",

                              "level":"global",

                              "unit":"sms",

                              "value": 10.0,

                              "valueLabel": "10 sms used",

                             "validFor": {

                                 "startDateTime": "2016-03-01T:00:00:00",

                                 "endDateTime": "2016-03-15T:00:00:00"

                             }

                         }

                     ]

             }

        ]

   }

 

usage consumption report request resource

This resource is used to manage the calculation request of an usage consumption report.

Resource model

Lifecycle

The usage consumption report request is tracked by mean of the status field. Typical lifecycle values are : inProgress (when the request is in progress) and done (when the request has been treated and the result is available) .

Note that an implementation of the specification may enrich the list of states depicted in the diagram or otherwise change the lifecycle, according to the CSP business practice.

Field descriptions

UsageConsumptionReportRequest

id

A string. Unique identifier of the usage consumption report request given by the server.

href

A string. Reference of the usage consumption report request.

creationDate

A date time (DateTime). Date and time of the request creation.

status

A string. Status of the usage consumption report request (InProgress or done).

lastUpdate

A date time (DateTime). Date when the status was last changed.

validPeriod

A time period (TimePeriod).

callbackUrl

A string. An url where the result could be notified.

product

A product reference (Product). Offer or option or which the usage consumption report is requested.

bucket

A list of buckets (Bucket[*]). Buckets for which the usage consumption report is requested.

relatedParty

A list of related parties (RelatedPartyRef[*]). Reference and role of the related parties for which the usage consumption report is requested.

Bucket

A bucket represents a quantity of usage, as 2 hours national calls or 50 sms for example. It could be either a quantity or an amount in a currency (i.e. It could represent a fixed number of SMS, MMS, minutes of calls, quantity of data, number of events as well as a specific amount in a given currency). It requires one or more network products from which usages will debit the bucket.

id

A string. Unique identifier of the bucket.

Product

An instantiated product corresponding to a simple product offering subscribed by a customer.

id

A string. Unique identifier of the product.

publicIdentifier

A string. Public number associated to the product (msisdn number for mobile line for example)

user

An user (RelatedPartyRef). Reference of the user of the product.

RelatedPartyRef

Related party reference.

id

A string. Unique identifier of a related party.

name

A string. Name of the related party.

role

A string. Role of the related party.

Json representation sample

We provide below the json representation of a sample of a “UsageConsumptionReportRequest” resource object corresponding to the use case 1 (usage consumption report requested for product identified by public identifier 0601010101 used by the user Kate) :

{

    "id": "ucrreq001",

    "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq001",

    "creationDate": "2016-03-15T:15:44:28",

    "status": "inProgress",

    "lastUpdate": "2016-03-15T:15:44:28",

    "product":  {

         "publicIdentifier ": "33601010101",

         "user": {

              "id": "usr1",

               "name": "Kate",

               "role": "user"

          }

    }

}

 

 

Notification Resource Models

1 notification is defined for this API.

Notification related to UsageConsumptionReportRequest :
    - UsageConsumptionReportRequestStateChangeNotification

 

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification resource (depicted by "SpecificNotification" placeholder) is a sub class of a generic Notification structure containing an id of the event occurence (eventId), an event timestamp (eventTime), and the name of the notification resource (eventType).

This notification structure owns an event structure ("SpecificEvent" placeholder) linked to the resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

.

usage consumption report request State Change Notification

Notification sent when changing the status of a UsageConsumptionReportRequest resource.

Json representation sample

We provide below the json representation of an example of a 'UsageConsumptionReportRequest StateChangeNotification' notification object

 

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"UsageConsumptionReportRequestStateChangeNotification",
     "event": {
        "usageConsumptionReportRequest" :
            {-- SEE  UsageConsumptionReportRequest  RESOURCE SAMPLE --}
    }
}
 

 

  API OPERATIONS

Remember the following Uniform Contract:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

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

 

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to execute Task Resources

Other Request Methods

POST on TASK Resource

GET and POST must not be used to tunnel other request methods.

 

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

Notifications are also described in a subsequent section.

 

 

Operations on usage consumption report

Query an usage consumption report in synchronous mode

  GET /usageReport?fields=...&{filtering}

Description

This operation is used to request the calculation of a new usage consumption report for a specific product identified by a msisdn number for example. It is used when a server could calculate and generate the usage consumption report In synchronous mode.

Attribute selection is enabled for all first level attributes.

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

Usage Samples

Here's an example of a request for retrieving an usage consumption report for use case 1 : given criteria is the msisdn number 0601010101 used by one user Kate :

 

Request
 

 

GET /usageManagement/usageConsumptionReport?product.publicIdentifier=33601010101

Accept: application/json
 


Response
 

 

200

[

{

    "id": "ucr0001",

    "href": "https://host:port/usageManagement/usageReport/ucr0001",

    "name": "Usage consumption report ucr0001",

    "description": "Usage consumption Report for Kate smartphone",

    "effectiveDate": "2016-03-15T:15:44:28",

    "bucket": [

        {

            "id": "bkt001",

            "name": "main offer data",

            "usageType": "data",

            "isShared": "false",

            "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                    "publicIdentifier": "33601010101",

                    "user": {

                 "id": "usr1",

                 "name": "Kate",

                 "role": "user"

             }

          },

          "bucketBalance": [

               {

                  "unit":"Go",

                  "remainingValue": 1.8,

                  "remainingValueLabel": "it remains 1.8 Go",

                  "validFor": {

                      "startDateTime": "2016-03-15T:00:00:00",

                     "endDateTime": "2016-03-30T:00:00:00"

                  }

               }

           ], 

           "bucketCounter": [

              {

                    "counterType":"used",

                    "level":"global",

                    "unit":"Go",

                    "value": 1.2,

                    "valueLabel": "1.2 Go used",

                    "validFor": {

                         "startDateTime": "2016-03-01T:00:00:00",

                         "endDateTime": "2016-03-15T:00:00:00"

                    }

                }

            ]

         },

        {

             "id": "bkt002",

             "name": "main offer national voice",

             "usageType": "national voice",

             "isShared": "false",

              "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                    "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

               },

              "bucketBalance": [

                   {

                       "unit":"mins",

                        "remainingValue": 80.0,

                       "remainingValueLabel": "it remains 80 minutes",

                       "validFor": {

                           "startDateTime": "2016-03-15T:00:00:00",

                          "endDateTime": "2016-03-30T:00:00:00"

                   }

                 }

              ], 

              "bucketCounter": [

                   {

                       "counterType":"used",

                       "level":"global",

                       "unit":"mins",

                       "value": 40.0,

                       "valueLabel": "40 mins used",

                       "validFor": {

                           "startDateTime": "2016-03-01T:00:00:00",

                          "endDateTime": "2016-03-15T:00:00:00"

                       }

                   }

             ]

         },

        {

              "id": "bkt003",

              "name": "main offer sms",

              "usageType": "sms",

              "isShared": "false",

               "product":  {

                     "id": "product1",

                     "name": "Main Offer",

                     "publicIdentifier": "33601010101",

                     "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

                 },

                "bucketBalance": [

                     {

                          "unit":"sms",

                          "remainingValue": 95.0,

                          "remainingValueLabel": "it remains 95 sms",

                          "validFor": {

                              "startDateTime": "2016-03-15T:00:00:00",

                              "endDateTime": "2016-03-30T:00:00:00"

                           }

                     }

                 ], 

                "bucketCounter": [

                     {

                        "counterType":"used",

                        "level":"global",

                        "unit":"sms",

                        "value": 25.0,

                        "valueLabel": "25 sms used",

                        "validFor": {

                            "startDateTime": "2016-03-15T:00:00:00",

                            "endDateTime": "2016-03-30T:00:00:00"

                        }

                     }

                ]

            },

            {

                 "id": "bkt004",

                 "name": "option Canada/USA voice",

                 "usageType": "Canada/USA voice",

                 "isShared": "false",

                 "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                      "user": {

                             "id": "usr1",

                              "name": "Kate",

                              "role": "user"

                         }

                      },

                     "bucketBalance": [

                         {

                             "unit":"mins",

                             "remainingValue": 10.0,

                             "remainingValueLabel": "it remains 10 minutes",

                             "validFor": {

                                  "startDateTime": "2016-03-15T:00:00:00",

                                  "endDateTime": "2016-03-30T:00:00:00"

                              }

                         }

                     ], 

                     "bucketCounter": [

                         {

                               "counterType":"used",

                               "level":"global",

                               "unit":"mins",

                               "value": 20.0,

                               "valueLabel": "20 mins used",

                               "validFor": {

                                   "startDateTime": "2016-03-01T:00:00:00",

                                   "endDateTime": "2016-03-15T:00:00:00"

                               }

                        } 

                    ]

               },

               {

                   "id": "bkt005",

                   "name": " Canada/USA sms",

                   "usageType": "sms",

                   "isShared": "false",

                   "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                            "name": "Kate",

                            "role": "user"

                         }

                      },

                   "bucketBalance": [

                        {

                            "unit":"sms",

                            "remainingValue": 0.0,

                            "remainingValueLabel": "Sms bucket exhausted",

                            "validFor": {

                                "startDateTime": "2016-03-15T:00:00:00",

                                "endDateTime": "2016-03-30T:00:00:00"

                            }

                        }

                     ], 

                     "bucketCounter": [

                         {

                              "counterType":"used",

                              "level":"global",

                              "unit":"sms",

                              "value": 10.0,

                              "valueLabel": "10 sms used",

                              "validFor": {

                                  "startDateTime": "2016-03-15T:00:00:00",

                                  "endDateTime": "2016-03-30T:00:00:00"

                               }

                         }

                     ]

             }

        ]

   }

]          

 

 

Here's an example of a request for retrieving an usage consumption report for use case 2 : given criteria is the msisdn number 0603030303 used by user Lea :


Request
 

 

GET /usageManagement/usageConsumptionReport?product.publicIdentifier =33603030303

Accept: application/json
 


Response
 

 

200

[ {

    "id": "ucr0002",

    "href": "https://host:port/usageManagement/usageConsumptionReport/ucr0002",

    "name": "Usage consumption report ucr0002",

    "description": "Usage Consumption Report for Lea phablet",

    "effectiveDate": "2016-03-15T:15:44:28",

     "bucket": [

        {

            "id": "bkt007",

            "name": "Shared data bucket",

            "usageType": "data",

            "isShared": "true",

            "product":  {

                "id": "product3",

                "name": "Shared data offer",

                "publicIdentifier":  "33603030303",

                "user": {

                        "id": "usr2",

                        "name": "Lea",

                        "role": "user"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"Go",

                        "remainingValue": 2.0,

                        "remainingValueLabel": "it remains 2.0 Go",

                        "validFor": {

                             "startDateTime": "2016-03-15T:00:00:00",

                             "endDateTime": "2016-03-30T:00:00:00"

                         }

                }

             ], 

             "bucketCounter": [

                 {

                     "counterType":"used",

                      "level":"global",

                      "unit":"Go",

                      "value": 3.0,

                      "valueLabel": "3.0 Go used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                         }

                  } ,

                 {

                     "counterType":"used",

                     "level":"detail",

                     "unit":"Go",

                     "value": 2.0,

                     "valueLabel": "2.0 Go used"

                 }

            ]

        }

    ]

} ]

 

 

Here's an example of a request for retrieving an usage consumption report for use case 2 : given criteria is the product reference product3 :


Request
 

 

GET /usageManagement/usageConsumptionReport?product.id=product3

Accept: application/json
 


Response
 

 

200

[ {

    "id": "ucr0003",

    "href": "https://host:port/usageManagement/usageConsumptionReport/ucr0003",

    "name": "Usage consumption report ucr0003",

    "description": "Usage Consumption Report for product3",

    "effectiveDate": "2016-03-15T:15:44:28",

     "bucket": [

        {

            "id": "bkt007",

            "name": "Shared data bucket",

            "usageType": "data",

            "isShared": "true",

            "product":  {

                "id": "product3",

                "name": "Shared data offer",

                 "user": {

                        "id": "usr2",

                        "name": "Lea",

                        "role": "user"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"Go",

                        "remainingValue": 2.0,

                        "remainingValueLabel": "it remains 2.0 Go",

                        "validFor": {

                             "startDateTime": "2016-03-15T:00:00:00",

                             "endDateTime": "2016-03-30T:00:00:00"

                        }

                 }

             ], 

             "bucketCounter": [

                 {

                     "counterType":"used",

                      "level":"global",

                      "unit":"Go",

                      "value": 3.0,

                      "valueLabel": "3.0 Go used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                         }

                  } ,

                  {

                     "counterType":"used",

                     "level":"detail",

                     "unit":"Go",

                     "value": 2.0,

                     "valueLabel": "2.0 Go used",

                     "product": {

                           "publicIdentifier":  "33603030303"

                     }

                 } ,

                  {

                     "counterType":"used",

                     "level":"detail",

                     "unit":"Go",

                     "value": 1.0,

                     "valueLabel": "1.0 Go used",

                     "product": {

                         "publicIdentifier": "33602020202"

                     }

                 }

            ]

        }

    ]

}]          

 

Here's an example of a request for retrieving an usage consumption report for use case 2 : given criteria is the user reference usr2 :


Request
 

 

GET /usageManagement/usageConsumptionReport?product.user.id=usr2

Accept: application/json
 


Response
 

 

200

[ {

    "id": "ucr0004",

    "href": "https://host:port/usageManagement/usageConsumptionReport/ucr0004",

    "name": "Usage consumption report ucr0004",

    "description": "Usage Consumption Report for user usr2",

    "effectiveDate": "2016-03-15T:15:44:28",

     "bucket": [

        {

            "id": "bkt007",

            "name": "Shared data bucket",

            "usageType": "data",

            "isShared": "true",

            "product":  {

                "id": "product3",

                "name": "Shared data offer",

                 "user": {

                        "id": "usr2",

                        "name": "Lea",

                        "role": "user"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"Go",

                        "remainingValue": 2.0,

                        "remainingValueLabel": "it remains 2.0 Go",

                        "validFor": {

                             "startDateTime": "2016-03-15T:00:00:00",

                             "endDateTime": "2016-03-30T:00:00:00"

                        }

                }

             ], 

             "bucketCounter": [

                 {

                     "counterType":"used",

                      "level":"global",

                      "unit":"Go",

                      "value": 3.0,

                      "valueLabel": "3.0 Go used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                        }

                  } ,

                  {

                     "counterType":"used",

                     "level":"detail",

                     "unit":"Go",

                     "value": 2.0,

                     "valueLabel": "2.0 Go used",

                     "product": {

                         "publicIdentifier ": "33603030303"

                        }

                 } ,

                  {

                     "counterType":"used",

                     "level":"detail",

                     "unit":"Go",

                     "value": 1.0,

                     "valueLabel": "1.0 Go used",

                     "product": {

                         "publicIdentifier": "33602020202"

                        }

                 }

            ]

        },

        {

             "id": "bkt008",

             "name": "main offer national voice",

             "usageType": "national voice",

             "isShared": "false",

              "product":  {

                   "id": "product4",

                   "name": "Main Offer",

                   "publicIdentifier": "33602020202",

                   "user": {

                           "id": "usr2",

                           "name": "Lea",

                           "role": "user"

                       }

               },

              "bucketBalance": [

                   {

                       "unit":"mins",

                        "remainingValue": 60.0,

                       "remainingValueLabel": "it remains 60 minutes",

                        "validFor": {

                             "startDateTime": "2016-03-15T:00:00:00",

                             "endDateTime": "2016-03-30T:00:00:00"

                        }

                   }

              ], 

              "bucketCounter": [

                   {

                       "counterType":"used",

                       "level":"global",

                       "unit":"mins",

                       "value": 60.0,

                       "valueLabel": "60 mins used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                        }

                   }

             ]

         },

        {

              "id": "bkt009",

              "name": "Main offer sms",

              "usageType": "sms",

              "isShared": "false",

                "product":  {

                     "id": "product4",

                     "name": "Main Offer",

                     "publicIdentifier": "33602020202",

 

                       "user": {

                           "id": "usr2",

                           "name": "Lea",

                           "role": "user"

                       }

                 },

                "bucketBalance": [

                     {

                          "unit":"sms",

                          "remainingValueLabel": "Unlimited sms"

                     }

                 ], 

                "bucketCounter": [

                     {

                        "counterType":"used",

                        "level":"global",

                        "unit":"sms",

                        "value": 123.0,

                        "valueLabel": "123 sms used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                        }

                     }

                ]

            }

    ]

}]

 

 

Here's an example of a request for retrieving an usage consumption report for use case 3 : given criteria is the product reference product5 :


Request
 

 

GET /usageManagement/usageConsumptionReport?product.id=product5

Accept: application/json
 


Response
 

 

200

[ {

    "id": "ucr0005",

    "href": "https://host:port/usageManagement/usageConsumptionReport/ucr0005",

    "name": "Usage consumption report ucr0004",

    "description": "Usage Consumption Report for shared data bucket",

    "effectiveDate": "2016-03-15T:15:44:28",

     "bucket": [

        {

            "id": "bkt0010",

            "name": "Shared data bucket",

            "usageType": "data",

            "isShared": "true",

            "product":  {

                "id": "product5",

                "name": "Shared data offer",

                 "user": {

                        "id": "usr1",

                        "name": "Kate",

                        "role": "user"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"Go",

                        "remainingValue": 1.8,

                        "remainingValueLabel": "it remains 1.8 Go",

                        "validFor": {

                             "startDateTime": "2016-03-15T:00:00:00",

                             "endDateTime": "2016-03-30T:00:00:00"

                        }

                }

             ], 

             "bucketCounter": [

                 {

                     "counterType":"used",

                      "level":"global",

                      "unit":"Go",

                      "value": 3.2,

                      "valueLabel": "3.2 Go used",

                        "validFor": {

                             "startDateTime": "2016-03-01T:00:00:00",

                             "endDateTime": "2016-03-15T:00:00:00"

                        }

                  } ,

                  {

                     "counterType":"used",

                     "level":"detailByUser",

                     "unit":"Go",

                     "value": 1.0,

                     "valueLabel": "1.0 Go used",

                     "user": {

                          "id": "usr1",

                         "name": "Kate"

                        }

                 } ,

                  {

                     "counterType":"used",

                     "level":"detailByUser",

                     "unit":"Go",

                     "value": 2.2,

                     "valueLabel": "2.2 Go used",

                     "user": {

                          "id": "usr2",

                         "name": "Lea"

                        }

                 } ,

                  {

                     "counterType":"used",

                     "level":"detailByDevice",

                     "unit":"Go",

                     "value": 1.0,

                     "valueLabel": "1.0 Go used",

                     "product": {

                         "publicIdentifier": "33601010101"

                        }

                 } ,

                  {

                     "counterType":"used",

                     "level":"detailByDevice",

                     "unit":"Go",

                     "value": 1.0,

                     "valueLabel": "1.0 Go used",

                     "product": {

                         "publicIdentifier": "33602020202"

                      }

                 },

                  {

                     "counterType":"used",

                     "level":"detailByDevice",

                     "unit":"Go",

                     "value": 1.2,

                     "valueLabel": "1.2 Go used",

                     "product": {

                         "publicIdentifier": "33603030303"

                        }

                 }

            ]

        }

    ]

}]

 

 

Retrieve usage consumption report

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

Description

This operation retrieves an usage consumption report entity. This operation could be used only if the server has saved the usage consumption report on its database after calculation.
Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's a sample of a request for retrieving a usageReport resource corresponding to use case 1.


Request
 

 

GET /usageManagement/usageConsumptionReport/ucr0001
Accept: application/json
 


Response
 

 

200

{

    "id": "ucr0001",

    "href": "https://host:port/usageManagement/usageReport/ucr0001",

    "name": "Usage report ur0001",

    "description": "Usage Report for Kate smartphone",

    "effectiveDate": "2016-03-15T:15:44:28",

    "bucket": [

        {

            "id": "bkt001",

            "name": "main offer data",

            "usageType": "data",

            "isShared": "false",

            "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                   "publicIdentifier": "33601010101",

                    "user": {

                      "id": "usr1",

                      "name": "Kate",

                     "role": "user"

                  }

              },

             "bucketBalance": [

                {

                  "unit":"Go",

                  "remainingValue": 1.8,

                  "remainingValueLabel": "it remains 1.8 Go",

                  "validFor": {

                      "startDateTime": "2016-03-15T:00:00:00",

                     "endDateTime": "2016-03-30T:00:00:00"

                  }

               }

           ], 

           "bucketCounter": [

              {

                    "counterType":"used",

                    "level":"global",

                    "unit":"Go",

                    "value": 1.2,

                    "valueLabel": "1.2 Go used",

                    "validFor": {

                         "startDateTime": "2016-03-01T:00:00:00",

                         "endDateTime": "2016-03-15T:00:00:00"

                    }

                }

            ]

         },

        {

             "id": "bkt002",

             "name": "main offer national voice",

             "usageType": "national voice",

             "isShared": "false",

              "product":  {

                   "id": "product1",

                    "name": "Main Offer",

                   "publicIdentifier": "33601010101",

                   "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

               },

              "bucketBalance": [

                   {

                       "unit":"mins",

                        "remainingValue": 80.0,

                       "remainingValueLabel": "it remains 80 minutes",

                   "validFor": {

                        "startDateTime": "2016-03-15T:00:00:00",

                       "endDateTime": "2016-03-30T:00:00:00"

                   }

                 }

              ], 

              "bucketCounter": [

                   {

                       "counterType":"used",

                       "level":"global",

                       "unit":"mins",

                       "value": 40.0,

                       "valueLabel": "40 mins used",

                       "validFor": {

                           "startDateTime": "2016-03-01T:00:00:00",

                          "endDateTime": "2016-03-15T:00:00:00"

                       }

                   }

             ]

         },

        {

              "id": "bkt003",

              "name": "main offer sms",

              "usageType": "sms",

              "isShared": "false",

               "product":  {

                     "id": "product1",

                      "name": "Main Offer",

                      "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                           "name": "Kate",

                           "role": "user"

                       }

                 },

                "bucketBalance": [

                     {

                          "unit":"sms",

                          "remainingValue": 95.0,

                          "remainingValueLabel": "it remains 95 sms",

                          "validFor": {

                              "startDateTime": "2016-03-15T:00:00:00",

                              "endDateTime": "2016-03-30T:00:00:00"

                           }

                     }

                 ], 

                "bucketCounter": [

                     {

                        "counterType":"used",

                        "level":"global",

                        "unit":"sms",

                        "value": 25.0,

                        "valueLabel": "25 sms used",

                        "validFor": {

                            "startDateTime": "2016-03-15T:00:00:00",

                            "endDateTime": "2016-03-30T:00:00:00"

                        }

                     }

                ]

            },

            {

                 "id": "bkt004",

                 "name": "option Canada/USA voice",

                 "usageType": "Canada/USA voice",

                 "isShared": "false",

                 "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                        "user": {

                             "id": "usr1",

                              "name": "Kate",

                              "role": "user"

                         }

                      },

                     "bucketBalance": [

                         {

                             "unit":"mins",

                             "remainingValue": 10.0,

                             "remainingValueLabel": "it remains 10 minutes",

                             "validFor": {

                                  "startDateTime": "2016-03-15T:00:00:00",

                                  "endDateTime": "2016-03-30T:00:00:00"

                              }

                         }

                     ], 

                     "bucketCounter": [

                         {

                               "counterType":"used",

                               "level":"global",

                               "unit":"mins",

                               "value": 20.0,

                               "valueLabel": "20 mins used",

                               "validFor": {

                                   "startDateTime": "2016-03-01T:00:00:00",

                                   "endDateTime": "2016-03-15T:00:00:00"

                               }

                        } 

                    ]

               },

               {

                   "id": "bkt005",

                   "name": " Canada/USA sms",

                   "usageType": "sms",

                   "isShared": "false",

                   "product":  {

                      "id": "product2",

                      "name": "Canada USA Pass",

                      "publicIdentifier": "33601010101",

                      "user": {

                           "id": "usr1",

                            "name": "Kate",

                            "role": "user"

                         }

                      },

                   "bucketBalance": [

                        {

                            "unit":"sms",

                            "remainingValue": 0.0,

                            "remainingValueLabel": "Sms bucket exhausted",

                            "validFor": {

                                "startDateTime": "2016-03-15T:00:00:00",

                                "endDateTime": "2016-03-30T:00:00:00"

                            }

                        }

                     ], 

                     "bucketCounter": [

                         {

                              "counterType":"used",

                              "level":"global",

                              "unit":"sms",

                              "value": 10.0,

                              "valueLabel": "10 sms used",

                              "validFor": {

                                  "startDateTime": "2016-03-15T:00:00:00",

                                  "endDateTime": "2016-03-30T:00:00:00"

                               }

                         }

                     ]

             }

        ]

   }

 

Create usage consumption report

  POST /usageConsumptionReport

Description

Note: this operation is not supported because the usage consumption report is dynamically calculated by the server.

Delete usage consumption report

  DELETE /usageConsumptionReport/{id}

Note: this operation is not available only to ADMIN API users

Description

This operation deletes a usage report entity.

Usage Samples

Here's an example of a request for deleting a usage report resource.


Request
 

 

DELETE /usageManagement/usageConsumptionReport/ucr0001
 


Response
 

 

204
 

 


Operations on usage consumption report Request

create an usage consumption report request

  POST /usageConsumptionReportRequest

Description

This operation creates an usage consumption report request entity. This operation is used by the requester when the server couldn’t calculate and generate the report in synchronous mode.

After, the API requester could follow the process with a GET operation on this same resource retrieving the status of the request. The server could also use the notification pattern to inform the API requester that the usage consumption report is available.

Mandatory and Non Mandatory attributes

Usage Samples

Here's an example of a request for requesting an usage consumption report for use case 1 : given criteria is the msisdn number 0601010101 used by one user Kate :

 

Request
 

 

POST /usageManagement/usageConsumptionReportRequest

Content-Type: application/json
 

{

     "product":  {

           "publicIdentifier": "33601010101",

            "user": {

                 "id": "usr1",

                 "name": "Kate",

                 "role": "user"

             }

     }

}

 


Response
 

 

201

{

    "id": "ucrreq001",

    "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq001",

    "creationDate": "2016-03-15T:15:44:28",

    "status": "inProgress",

    "lastUpdate": "2016-03-15T:15:44:28",

}

 

 

Here's an example of a request for requesting an usage consumption report for use case 2 : given criteria is the msisdn number 0603030303 used by user Lea :


Request
 

 

POST /usageManagement/usageConsumptionReportRequest

Content-Type: application/json
 

{

     "product":  {

          "publicIdentifier": "33603030303",

           "user": {

                 "id": "usr2",

                 "name": "Lea",

                 "role": "user"

            }

     }

}

 


Response
 

 

201

{

    "id": "ucrreq002",

    "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq002",

    "creationDate": "2016-03-15T:15:44:28",

    "status": "inProgress",

    "lastUpdate": "2016-03-15T:15:44:28",

}

 

 

Here's an example of a request for requesting an usage consumption report for use case 2 : given criteria is the product reference product3 :


Request
 

 

POST /usageManagement/usageConsumptionReportRequest

Content-Type: application/json
{

     "product":  {

          "id": "product3",

     }

}

 


Response
 

 

201

{

    "id": "ucrreq003",

    "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq003",

    "creationDate": "2016-03-15T:15:44:28",

    "status": "inProgress",

    "lastUpdate": "2016-03-15T:15:44:28",

}

 

 

Here's an example of a request for requesting an usage consumption report for use case 2 : given criteria is the user reference usr2 :


Request
 

 

POST /usageManagement/usageConsumptionReportRequest

Content-Type: application/json
 

{

     "relatedParty": [

        {

           "id": "usr2",

           "name": "Lea",

           "role": "user"

        }

     ]

}

 


Response
 

 

201

{

    "id": "ucrreq004",

    "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq004",

    "creationDate": "2016-03-15T:15:44:28",

    "status": "inProgress",

    "lastUpdate": "2016-03-15T:15:44:28",

}

 

LIst usage consumption report requests

  GET /usageConsumptionReportRequest?fields=...&{filtering}

Description

This operation is used to retrieve usage consumption report requests corresponding to search criteria like a specific product identified by a msisdn number for example.

Attribute selection is enabled for all attributes.

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

Usage Samples

Here's an example of a request for retrieving usage consumption report requests for use case 1 : given criteria is the msisdn number 0601010101 used by one user Kate :

 

Request
 

 

GET /usageManagement/usageConsumptionReportRequest?product.publicIdentifier=33601010101

Accept: application/json
 


Response
 

 

200

[

  {

      "id": "ucrreq001",

      "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq001",

      "creationDate": "2016-03-15T:15:44:28",

      "status": "inProgress",

      "lastUpdate": "2016-03-15T:15:44:28",

  }

]          

 

 


retrieve usage consumption report request

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

Description

This operation retrieves an usage consumption report request entity using its unique id.

Attribute selection is enabled for all attributes.

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

Usage Samples

Here's an example of a request for retrieving an usage consumption report request completed

corresponding to use case 1 :

 

Request
 

 

GET /usageManagement/usageConsumptionReportRequest/uccreq001

Accept: application/json
 


Response
 

 

200

  {

      "id": "ucrreq001",

      "href": "https://host:port/usageManagement/usageConsumptionReportRequest/ucrreq001",

      "creationDate": "2016-03-15T:15:44:28",

      "status": "done",

      "lastUpdate": "2016-03-16T:15:44:28",

      "usageConsumptionReport":

        {

             "id": "ucr0001",

             "href": "https://host:port/usageManagement/usageReport/ucr0001",

             "name": "Usage report ur0001",

             "description": "Usage Report for Kate smartphone",

             "effectiveDate": "2016-03-15T:15:44:28"

        }

}    

 

 


Delete usage consumption report request

  DELETE /usageConsumptionReportRequest/{id}

Note: this operation is not available only to ADMIN API users

Description

This operation deletes an usage consumption report request entity.

Usage Samples

Here's an example of a request for deleting an usage consumption report request resource.


Request
 

 

DELETE /usageManagement/usageConsumptionReportRequest/ucrreq0001
 


Response
 

 

204
 

 

 

API NOTIFICATIONS

For every single of operation on the entities use the following templates and provide sample REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.

Register listener

  POST /hub

Description

Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.


Request
 

POST /api/hub

Accept: application/json

 

{"callback": "http://in.listener.com"}
 


Response
 

201

Content-Type: application/json

Location: /api/hub/42

 

{"id":"42","callback":"http://in.listener.com","query":null}

 

 


Unregister listener

  DELETE /hub/{id}

Description

Clears the communication endpoint address that was set by creating the Hub..

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.


Request
 

 

DELETE /api/hub/42

Accept: application/json
 


Response
 

204

 

Publish Event to listener

  POST /client/listener

Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY refers to the data structure of the given notification type.


Request
 

 

POST /client/listener

Accept: application/json

 

{

    "event": {

                EVENT BODY

            },

    "eventType": "EVENT_TYPE"

}
 


Response
 

201

 

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design Guidelines.


Acknowledgements

 

Release History

 

Release Number

Date

Release led by:

Description

Release 1.0

06/09/2017

Orange

Telefonica

First Release of Draft Version of the Document.