Page tree

 

 

 

 

 

 

 

Usage Consumption API
Conformance Profile

 

Document Number TMF677B

June 2017

 

 

 

 

 

 

 

Release: Frameworx Release 17.5

Status: Member Evaluation

Version: 1.0.0

IPR Mode: RAND

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

 

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

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

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

 

Direct inquiries to the TM Forum office:

4 Century Drive
Suite 100
Parsippany, NJ 07054, USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

API DESCRIPTION

RESOURCE MODEL CONFORMANCE

UsageConsumption API MANDATORY AND OPTIONAL RESOURCES

UsageConsumptionReport resource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

Usage Consumption MANDATORY AND OPTIONAL OPERATIONS

API GET FILTERING OPERATION CONFORMANCE

Filtering in UsageConsumptionReport resource

GET /usageManagement/v1/usageConsumptionReport

GET /usageManagement/v1/usageConsumptionReport/{usageConsumptionReportId}

API CONFORMANCE TEST SCENARIOS

Usage Consumption Report resource TEST CASES

 

List of Tables

 

No table of figures entries found.

 

Introduction

The following document is the REST API Conformance for the Usage Consumption API.

API DESCRIPTION

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.

RESOURCE MODEL CONFORMANCE

UsageConsumption API MANDATORY AND OPTIONAL RESOURCES

 

Resource Name

Mandatory or Optional

Comments

UsageConsumptionReport

M

 

 

 

UsageConsumptionReport resource MANDATORY AND OPTIONAL ATTRIBUTES

Attribute Name

Mandatory or Optional

Comments

id

O

Only required if the server stores reports for future individual resource requests

href

O

Only required if the server stores reports for future individual resource requests

name

M

 

 

description

O

 

effectiveDate

M

 

bucket

M

Array of structures including at least one entity

 

id

M

 

 

name

O

 

 

usageType

O

 

 

isShared

O

If not included indicates not shared

 

product

M

 

 

 

id

M

 

 

 

href

O

 

 

 

name

O

 

 

 

publicIdentifier

O

 

 

 

user

O

 

 

 

 

id

M if user included

 

 

 

 

name

O

 

 

 

 

role

O

 

 

bucketBalance

M if bucketCounter not included

Mandatory if bucketCounter not included

Array of structures including at least one entity

 

 

unit

M if bucketBalance included

 

 

 

remainingValue

M if bucketBalance included

 

 

 

remainingValueLabel

O

 

 

 

validFor

O

 

 

 

 

startDateTime

M if validFor included

 

 

 

 

endDateTime

O

 

 

bucketCounter

M if bucketBalance not included

Mandatory if bucketBalance not included

Array of structures including at least one entity

 

 

countertype

O

 

 

 

level

O

 

 

 

unit

M if bucketCounter included

 

 

 

value

M if bucketCounter included

 

 

 

valueLabel

O

 

 

 

validFor

O

 

 

 

 

startDateTime

M if validFor included

 

 

 

 

endDateTime

O

 

relatedParty

O

Array of structures

 

id

M If relatedParty included

 

 

name

O

 

 

role

O

 

 

API OPERATIONS CONFORMANCE

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

Usage Consumption MANDATORY AND OPTIONAL OPERATIONS

 

Uniform API Operation

Mandatory/Optional

Comments

GET

M

GET must be used to retrieve a representation of a resource

 

POST

NA

POST must be used to create a new resource

PUT

NA

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

PATCH (JSON-PATH)

NA

PATCH must be used to partially update a resource

DELETE

NA

DELETE must be used to remove a resource

 

 

 

 

API GET FILTERING OPERATION CONFORMANCE

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.:?name=<value> &owner.id=<value>)

 

Filtered Response Data (Response 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=name,description will provide in the response only the values assigned to attributes name and description). Attribute selection capabilities are the same for collections retrieval and individual resource queries

 

Filtering in UsageConsumptionReport resource

Attribute name

Filtered search

First Level

Filtered search

N Level

Response Attribute Selection

First Level

Response Attribute Selection

N Level

id

NA

NA

M

NA

href

NA

NA

M

NA

name

O

NA

M

NA

description

NA

NA

M

NA

effectiveDate

NA

NA

M

NA

bucket

NA

O

M

O

bucket.product

NA

O

(id)

(name)

(publicIdentifier)

(user)

M

NA

bucket.bucketBalance

NA

NA

M

NA

bucket.bucketCounter

NA

O

(validFor)

M

NA

relatedParty

NA

O

(id)

(name)

(role)

M

NA

 

GET /usageManagement/v1/usageConsumptionReport

 

 

Filtered Search: A filtered search can be applied using the following filtering criteria

 

  • bucket.bucketCounter.validFor.startDateTime: to obtain the reports where the usage was measured from a given moment in time

 

  • bucket. bucketCounter.validFor.endDateTime: to obtain the reports where the usage was measured until a given moment in time

 

  • bucket.product.id: to obtain the reports for a given product identified by id

 

  • bucket.product.name: to obtain the reports for a given product identified by name

 

  • bucket.publicIdentifier: to obtain the reports for a given product identified by public id

 

  • bucket.user.id: to obtain the reports for a given user identified by id

 

  • bucket.user.name: to obtain the reports for a given user identified by name

 

  • relatedParty.id: to obtain the reports related to a given party identified by id

 

  • relatedParty.name: to obtain the reports related to a given party identified by name

 

  • relatedParty.role: to obtain the reports related to a given party with a given role

 

 

 

 

Filtered Response Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of Usage Consumption Report resource definition

 

-           Any of the attributes in the second level of Usage Consumption Report resource definition under bucket (bucket.product, bucket.product.user, bucket.bucketBalance, bucket.bucketCounter)

 

 

GET /usageManagement/v1/usageConsumptionReport/{usageConsumptionReportId}

Filtered Response Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of Usage Consumption Report resource definition

 

-           Any of the attributes in the second level of Usage Consumption Report resource definition under bucket (bucket.product, bucket.product.user, bucket.bucketBalance, bucket.bucketCounter)

 

 

API CONFORMANCE TEST SCENARIOS

This section describes the test scenarios required for the basic CONNECT certification of Usage Consumption API.

Test Cases must be executed in the order defined for each resource because the result from one of the scenarios will be input for the next one.

Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/usageManagement/v1 , being {serverRoot} the certification endpoint

 

Usage Consumption Report resource TEST CASES

Nominal Scenarios

TC_UsageReport_N1 – Request usage reports

  • Register the following definition of usage reports in the server environment to simulate usage in the current month (validity period between first and last day of the current month)

usageReport = ur001

name = report1

user = u1

product_Id = p111

bucket_Id=b111

type of bucket = data

measurement period = first to last day of the month

usage in measured period = 3 MB

balance till the end of the month = 2 MB

 

usageReport = ur002

name = report2

user = u1

product_Id = p222

bucket_Id=b222

type of bucket = voice

measurement period = first to last day of the month

usage in measured period = 500 minutes

balance till the end of the month = 300 minutes

 

usageReport = ur003

name = report3

user = u2

product_Id = p333

bucket_Id=b331

type of bucket = sms

measurement period = first to last day of the month

usage in measured period = 150 message

balance in the period = 149 messages

 

product_Id = p222

bucket_Id=b332

type of bucket = national voice

measurement period = first to last day of the month

usage in measured period = 500 minutes

balance till the end of the month = 340 minutes

 

 

  • Send a GET message to {apiRoot}/ usageConsumptionReport

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes three UsageConsumptionReport resources with IDs set to ur001, ur002 & ur003, the same identifiers as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[ {

    "id": "ur001",

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

    "name": "report 1",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b111",

            "usageType": "data",

            },

            "product":  {

                "id": "p111",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"MB",

                        "remainingValue": 2.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"MB",

                      "value": 3.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

         ]

    },

    {

    "id": "ur002",

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

    "name": "report 2",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b222",

            "usageType": "voice",

            },

            "product":  {

                "id": "p222",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"minutes",

                        "remainingValue": 300.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"minutes",

                      "value": 500.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

           }

         ]

    };

"id": "ur003",

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

    "name": "report 3",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b331",

            "usageType": "data",

            "product":  {

                "id": "p333",

                 "user": {

                        "id": "u2"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"messages",

                        "remainingValue": 149.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                  }

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"messages",

                      "value": 150.0,

        "validFor": {

             "startDateTime": <first day of current month>,

             "endDateTime": <date when report is requested>

                       }

                  }

            ]

        },

        {

            "id": "b332",

            "usageType": "voice",

            "product":  {

                "id": "p222",

                 "user": {

                        "id": "u2"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"minutes",

                        "remainingValue": 340.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                        }

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"minutes",

                      "value": 500.0,

        "validFor": {

             "startDateTime": <first day of current month>,

             "endDateTime": <date when report is requested>

                        }

                  }

            ]

           }

         ]

    }

]

 

TC_UsageReport_N2 – Request usage report for specific user

  • Send a GET message to {apiRoot}/ usageConsumptionReport ?relatedParty.id=u1

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes two UsageConsumptionReport resources with IDs set to ur001 & ur002, the same identifiers as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[

    "id": "ur001",

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

    "name": "report 1",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b111",

            "usageType": "data",

            },

            "product":  {

                "id": "p111",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"MB",

                        "remainingValue": 2.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"MB",

                      "value": 3.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

         ]

    },

    {

    "id": "ur002",

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

    "name": "report 2",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b222",

            "usageType": "voice",

            },

            "product":  {

                "id": "p222",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"minutes",

                        "remainingValue": 300.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"minutes",

                      "value": 500.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

           }

         ]

    }

]

 

  • Send a GET message to {apiRoot}/ usageConsumptionReport ?relatedParty.id=u2

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one UsageConsumptionReport resource with ID set to ur003, the same identifier as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[

{

"id": "ur003",

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

    "name": "report 3",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b331",

            "usageType": "data",

            "product":  {

                "id": "p333",

                 "user": {

                        "id": "u2"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"messages",

                        "remainingValue": 149.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                  }

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"messages",

                      "value": 150.0,

        "validFor": {

             "startDateTime": <first day of current month>,

             "endDateTime": <date when report is requested>

                       }

                  }

            ]

        },

        {

            "id": "b332",

            "usageType": "voice",

            "product":  {

                "id": "p222",

                 "user": {

                        "id": "u2"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"minutes",

                        "remainingValue": 340.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                        }

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"minutes",

                      "value": 500.0,

        "validFor": {

             "startDateTime": <first day of current month>,

             "endDateTime": <date when report is requested>

                        }

                  }

            ]

           }

         ]

    }

]

 

TC_UsageReport_N3 – Request usage report for specific product

 

  • Send a GET message to {apiRoot}/ usageConsumptionReport ?bucket.product.id=p333

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one UsageConsumptionReport resource with ID set to ur003 including at least the usage information regarding product p333, the same identifier as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[

{

"id": "ur003",

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

    "name": "report 3",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b331",

            "usageType": "data",

            "product":  {

                "id": "p333",

                 "user": {

                        "id": "u2"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"messages",

                        "remainingValue": 149.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                  }

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"messages",

                      "value": 150.0,

        "validFor": {

             "startDateTime": <first day of current month>,

             "endDateTime": <date when report is requested>

                       }

                  }

            ]

        }

     }

]

 

TC_UsageReport_N4 – Request specific usage report

 

  • Send a GET message to {apiRoot}/ usageConsumptionReport/ur002

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one UsageConsumptionReport resource with ID set to ur002, the same identifier as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[ {

    "id": "ur002",

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

    "name": "report 2",

    "effectiveDate": <any valid date>,

     "bucket": [

        {

            "id": "b222",

            "usageType": "voice",

            },

            "product":  {

                "id": "p222",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"minutes",

                        "remainingValue": 300.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"minutes",

                      "value": 500.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

           }

         ]

    }]

 

TC_UsageReport_N5 – Filtered data response

  • Send a GET message to {apiRoot}/ usageConsumptionReport/ur001?fields=id,bucket

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one UsageConsumptionReport resource with ID set to ur001, the same identifier as originally registered in the server

 

-           The response message includes all mandatory parameters and the values originally registered in the server

 

 

[ {

    "id": "ur001",

     "bucket": [

        {

            "id": "b111",

            "usageType": "data",

            },

            "product":  {

                "id": "p111",

                 "user": {

                        "id": "u1"

                   }

              },

            "bucketBalance": [

                {

                        "unit":"MB",

                        "remainingValue": 2.0,

        "validFor": {

             "startDateTime": <date when report is requested>,

             "endDateTime": <last day of current month>

                }

             ], 

             "bucketCounter": [

                 {

                      "unit":"MB",

                      "value": 3.0,

      "validFor": {

           "startDateTime": <first day of current month>,

           "endDateTime": <date when report is requested>

                  }

            ]

         ]

    }]

 

 

Error Scenarios

A GET request to retrieve a usage report for a product or user not defined will return a 200-OK with an empty array of Usage Consumption Reports resources.

 

TC_ UsageReport _E1 – Unknown user

  • Send a GET message to {apiRoot}/ usageConsumptionReport ?relatedParty.id=u000   where u000 does not match any of the identifiers previously creted in the server

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

-           Empty body

 

 

TC_ UsageReport _E1 – Unknown product

  • Send a GET message to {apiRoot}/ usageConsumptionReport ?bucket.product.id=p000   where p000 does not match any of the identifiers previously creted in the server

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

-           Empty body