Page tree

 

Service Quality Management API REST SPECIFICATION

 

Document Number:  <###>

Document Version: : <V0.2>

Date:  July, 2016

Document Status: Draft

NOTICE

Copyright © TeleManagement Forum 2013. All Rights Reserved.

 

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

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

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

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

Sample Use Cases

Resource model

Managed Entity and Task Resource Models

Service Level Objective Resource

Service Level Specification

Notification Resource Models

Service Level Objective Creation Notification

Service Level Objective Attribute value change Notification

Service Level Objective Remove Notification

Service Level Specification Creation Notification

Service Level Specification Remove Notification

API OPERATION

Operations on Service Level Objective

List Service Level Objective

Retrieve Service Level Objective

Create Service Level Objective

Patch Service Level Objective

Delete Service Level Objective

Operations on Service Level SPECIFICATION

List Service Level SPECIFICATION

Retrieve Service Level SPECIFICATION

Create Service Level SPECIFICATION

Patch Service Level SPECIFICATION

Delete Service Level SPECIFICATION

API NOTIFICATIONS

Register listener

Unregister listener

Publish Event to listener

Release History

 

List of Tables

 

 

Introduction

The following document is the Service Quality Management REST API Specification.

As the Digital Economy emerges, the Digital Service Providers, Consumers and Developers are striving to take advantage of Open Digital Eco-system to create, manage and support new Digital Services.

In this context, the ability to deliver consistent digital services experience across the Eco-system between different enterprises is considered table-stakes. This focus on digital service delivery and quality has positioned Service Quality Management at the center of Digital Operations.

Gathering data from multiple and heterogeneous data sources across the eco-system, combining them into meaningful service quality metrics is the core activity of a Service Quality Management application to assess the quality as perceived by the consumer.

Once the measurements are available, they must be watched against contracted service level to ensure consistent delivery as committed to in Service Level Agreements (SLA). The Service Quality Management API defines a standard interface designed to simplify the integration task of an SQM application with different partners and respective Digital Operations Centers. This API follows the RESTful design principles.

Through this API, any Enterprise is able to access a Service Quality Management application and extract Service Level Specifications and associated Service Level Objectives (SLO) and their thresholds. They are able to monitor violation of these thresholds and generate trending reports over a period of time and send threshold crossing alarms so that when service quality degrades and a contracted Service Level Agreement (or one of its constituents) is at risk, appropriate actions can be performed.

 

 

SAMPLE USE CASES

The Use Case Id, UC_TMF_ServiceQualityManagement_0001 is for the Service Quality Monitoring function. The next use case is UC_TMF_ServiceQualityManagement_0002 for Service Quality Reporting function. The next use case is UC_TMF_ServiceQualityManagement_0003 for Service Quality Alarming function.

Sample Use Cases

Use Case Id

UC_TMF_ServiceQualityManagement_0001

Use Case Name

Service Quality Monitoring

Summary

The SQM API enables Clients within external or internal systems to access the Service Quality Management Application and monitor the quality of specified services against their SLOs

Actor(s)

Clients’ resident external and internal to the Enterprise as described in figure 3 are acting as the Consumer. SQM Application is the actor acting as the Producer.

Pre-Conditions

a)        SLAs between Enterprise and Service Provider have been agreed and defined, which represents contractual agreement between parties for quality of specific services

b)        OLAs (Operations Level Agreements) between Customer Care Operations and Service Management Center of the Service Provider should be agreed and defined, which represents agreement between Departments for quality of specific services

c)        SLOs representing actual thresholds to be monitored have been defined

d)        SLOs have been mapped to Key Quality Indicators for the services monitored by the Service Quality Management application

Begins When

When all pre-conditions have been met and agreed period of monitoring between the Client and Service Quality Management Application starts

Description

This functionality enables the Client of Service Quality Management Application to Create/Query/Delete Service Level Agreements, its items, Service Level Specifications and Service Level Objectives

AND

Register for notifications when defined Service Level Objectives are at breach and the contracted SLA or OLA is at risk.

These notifications trigger appropriate actions for resolution.

Ends When

In case of termination of contract or agreement and there is no need for monitoring or the agreed period for monitoring has come to an end

Post-Conditions

In case of no breach of Service Level Objectives:

  1. The Client continues to montior in an ongoing basis
  2. Occasionally the client may update and modify the SLAs/SLOs or introduce new services

 

In case of breach of Service Level Objectives:

  1. Notifications are sent to the Client system to ensure preventive measures can be taken and ensure there is no impact to Business and if there is any loss then it can be minimized
  2. Notifications are sent to the Service Provider systems so Root Cause Analysis can be performed and corrective action trigered for resolution.

Exceptions

  1. In case of regular maintenance or system upgrades there may be planned outages that are part of agreed breach of SLOs and generated notifications should be ignored. There should be exception raised with the Client and suggest the notification is misleading ‘Ignore Notifications for this period, due to Routine Maintenance’
  2. In case the mandatory details are invalid then an ‘Invalid input’ exception shall be raised along with the details of validation failure and thus the operation is not fulfilled
  3. In case the authentication of the Requesting Client is not validated by the Service Quality Management application  then an ‘Access Denied’ exception shall be raised and the operation is not fulfilled
  4. If the SQM Application is unable to accomplish the operation, due to a lack of internal resources then an ‘Unable To Execute’ exception shall be raised and the operation is not fulfilled.
  5. If the SQM Application is unable to accomplish the operation, due to any other internal error, then an ‘Internal Error’ exception shall be raised and the operation is not fulfilled.

Traceability

R_TMF_ServiceQualityManagement_I_0001

 

 

 

 

Use Case Id

UC_TMF_ServiceQualityManagement_0002

Use Case Name

Service Quality Reporting

Summary

The SQM API enables Clients to define and schedule the delivery of Service Quality Reports.

Actor(s)

Clients’ resident external and internal to the Enterprise as described in figure 3 are acting as the Consumer. SQM Application is the actor acting as the Producer.

Pre-Conditions

  1. SLAs between Enterprise and Service Provider have been agreed and defined, which represents contractual agreement between parties for quality of specific services
  2. OLAs (Operations Level Agreements) between Customer Care Operations and Service Management Center of the Service Provider should be agreed and defined, which represents agreement between Departments for quality of specific services
  3. SLOs representing actual thresholds to be monitored have been defined
  4. SLOs have been mapped to Key Quality Indicators for the services monitored by the Service Quality Management application
  5. Data must have been collected and stored for Service Quality and easily accessible to generate the reports

Begins When

When all pre-conditions have been met and the Client desires to build different types of reports for a specific period

Description

SQM API allows a client of the API to trigger the generation of Service Quality Reports, containing information to track how the various Service Level Agreement Items as well as the Service Level Objectives have been delivered over time and there are any observable trends.

The reports can be scheduled defining the sample period and the reporting period, as well as other attributes such as the format of the report, how it should be delivered, etc.

Ends When

In case of success:

The Client has received the Reports for the specified period

In case of failure:

The Client has not received the Reports for the specified period

Post-Conditions

 

Exceptions

  1. In case of regular maintenance or system upgrades there may be planned outages that are part of agreed breach of SLOs and generated reports for that period should be ignored. There should be exception raised with the Client and suggest the data is misleading ‘Ignore Reports during this period, due to Routine Maintenance’
  2. In case the mandatory details are invalid then an ‘Invalid input’ exception shall be raised along with the details of validation failure and thus the operation is not fulfilled
  3. In case the authentication of the Requesting Client is not validated by the Service Quality Management application  then an ‘Access Denied’ exception shall be raised and the operation is not fulfilled
  4. If the SQM Application is unable to accomplish the operation, due to a lack of internal resources then an ‘Unable To Execute’ exception shall be raised and the operation is not fulfilled.
  5. If the SQM Application is unable to accomplish the operation, due to any other internal error, then an ‘Internal Error’ exception shall be raised and the operation is not fulfilled.

Traceability

R_TMF_ServiceQualityManagement_I_0001

 

 

 

 

Use Case Id

UC_TMF_ServiceQualityManagement_0003

Use Case Name

Service Quality Alarming

Summary

The SQM API enables Client to access Service Quality Alarms that have been raised as a result of a Service Level Specification being violated. It provides the basic functionalities of an Alarm Manager.

Actor(s)

Clients’ resident external and internal to the Enterprise as described in figure 3 are acting as the Consumer. SQM Application is the actor acting as the Producer.

Pre-Conditions

a)        SLAs between Enterprise and Service Provider have been agreed and defined, which represents contractual agreement between parties for quality of specific services

b)        OLAs (Operations Level Agreements) between Customer Care Operations and Service Management Center of the Service Provider should be agreed and defined, which represents agreement between Departments for quality of specific services

c)        SLOs representing actual thresholds to be monitored have been defined

d)        SLOs have been mapped to Key Quality Indicators for the services monitored by the Service Quality Management application

e)        Alarms must have been generated and stored with the Service Quality Management Application so can be accessed by Client

f)         Alarms that are still Active or have been Cleared, both should be provided by SQM application to Client

Begins When

When all pre-conditions have been met and the Client sends request to SQM Application to provide information on list of all active and cleared alarms for a specific time period

Description

  1. The Client sends request for Active and Cleared Alarms
  2. The SQM Application validates the request
  3. The SQM Application prepares the list of all active and cleared alarms
  4. The Client receives the list of all Active & Cleared Alarms

Ends When

In case of success:

The Client has received the Alarm data for the specified period

In case of failure:

The Client has not received the Alarm data for the specified period

Post-Conditions

In case of success:

The Client has received the same Alarms information as generated within the Service Quality Management Application

In case of failure:

The Client is not aware of the Alarm generated within the Service Quality Management application and the data on Client is inconsistent

Exceptions

1)        In case of regular maintenance or system upgrades there may be planned outages that are part of agreed breach of SLOs and generated Alarms should be ignored. There should be exception raised with the Client and suggest the alarms generated should have a tag suggesting ‘Ignored due to Routine Maintenance’

2)        In case the mandatory details are invalid then an ‘Invalid input’ exception shall be raised along with the details of validation failure and thus the operation is not fulfilled

3)        In case the authentication of the Requesting Client is not validated by the Service Quality Management application  then an ‘Access Denied’ exception shall be raised and the operation is not fulfilled

4)        If the SQM Application is unable to accomplish the operation, due to a lack of internal resources then an ‘Unable To Execute’ exception shall be raised and the operation is not fulfilled.

5)        If the SQM Application is unable to accomplish the operation, due to any other internal error, then an ‘Internal Error’ exception shall be raised and the operation is not fulfilled.

Traceability

R_TMF_ServiceQualityManagement_I_0001


Resource model

Managed Entity and Task Resource Models

There are two resources managed by the API as listed below and JSON representation of the managed entities and tasks is mentioned following that.

  • Service Level Objectives
  • Service Level Specifications

The representation is based on the SID and API data model perspective.

SERVICE LEVEL OBJECTIVE RESOURCE

Service level objective is the quality goal for a Service Level Specification defined in terms of parameters and metrics, thresholds, and tolerances associated with the parameters.

Resource Model

Fig.1: Service Level Objective

Field descriptions

ConformancePeriod fields

An interval of time during which the Conformance Target must be measured.

endDateTime

A DateTime. The end date and time.

startDateTime

A DateTime. The start date and time.

 

RelatedEntityRef fields

The related entity source of a KQI or KPI. A KQI draws its data from a number of sources, including Key Performance Indicators (KPIs).  A KPI provides a measurement of a specific aspect of the performance of a Service (whether it is a network- or a non-network-based Service) or a group of Services of the same type.

herf

A String. The hyperlink to access an entity.

id

A String. The identifier of an entity.

name

A String. The name of an entity.

 

ServiceLevelSpecConsquence fields

Some consequences for the provider of the Service are resulted when the service level objective does not meet.

prescribedAction

A String. Recommended remedy for a violated Service Level Objective. This could be a hyperlink to the recommended action.

validFor

The period of time during which the objective is applicable.

 

ServiceLevelSpecParameter fields

Service Level Specification parameters can be one of two types. A Key Quality Indicator (KQI) provides a measurement of a specific aspect of the performance of a Product (i.e., Product Specification, Product Offering, or Product) or a Service (i.e., Service Specification or Service).

name

A string. The name of parameter.

serviceParmCategory

A String. A string that specifies whether the Service Level Specification Parameter is technology specific, service specific, or technology/service independent

serviceParmPerspective

A String. A string that specifies whether the Service Level Specification Parameter represents a single user instance parameter or a parameter that represents an aggregation.

transformationAlgorithmOfKQI

A String. The description of a logical step-by-step procedure used to calculate the value of a KQI.

type

A String. Types of Service Level Specification parameters are KQI or KPI

validFor

The period of time during which the objective is applicable.

relatedEntityRef

The related entity source of a KQI or KPI. A KQI draws its data from a number of sources, including Key Performance Indicators (KPIs).  A KPI provides a measurement of a specific aspect of the performance of a Service (whether it is a network- or a non-network-based Service) or a group of Services of the same type.

 

ServiecLevelObjective fields

Service level objectives are defined in terms of parameters and metrics, thresholds, and tolerances associated with the parameters.

conformanceComparator

A String. An operator that specifies whether a Service Level Objective is violated above or below the conformanceTarget.

conformanceTarget

A String. A value used to determine if Service Level Objective is met. The data type should be adjusted case by case.

graceTimes

An int. The number of times an objective can remain un-updated without a violation of a Service Level Agreement in reference to a measurement period and/or Service Level Agreement reporting period.

href

A String. The hyperlink to access a service level objective.

id

A String. The identifier of a service level objectives.

name

A String. The name of the service level objectives.

thresholdTarget

A String. A value that used to specify when a warning should be used that indicates an objective is danger of not being met. Notice, the data type should be adjusted case by case.

toleranceTarget

A String. A value that specifies the allowable variation of a conformance Target. The data type should be adjusted case by case.

conformancePeriod

An interval of time during which the Conformance Target must be measured.

validFor

The period of time during which the objective is applicable.

serviceLevelSpecConsquence

Some consequences for the provider of the Service are resulted when the service level objective does not meet.

tolerancePeriod

An interval of time over which the tolerance Target is acceptable before indication of an objective violation.

serviceLevelSpecParameter

Service Level Specification parameters can be one of two types. A Key Quality Indicator (KQI) provides a measurement of a specific aspect of the performance of a Product (i.e., Product Specification, Product Offering, or Product) or a Service (i.e., Service Specification or Service).

 

TolerancePeriod fields

An interval of time over which the tolerance Target is acceptable before indication of an objective violation.

endDateTime

A DateTime. The end date and time.

startDateTime

A DateTime. The start date and time.

 

ValidFor fields

The period of time during which the objective is applicable.

endDateTime

A DateTime. The end date and time.

startDateTime

A DateTime. The start date and time.

 

JSON representation sample

We provide below the JSON representation of an example of Service Level Objective object:  

{

    "href": "https://host:port/SQM/serviceLevelObjective/3112",

    "id": "3112",

    "conformanceCompartor": "above",

    "conformanceTargarget": "32",

    "conformancePeriod": {

        "endDateTime": "2017-03-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

    },

    "graceTimes": 3,

    "name": "ObjectiveToSpeed",

    "thresholdTarget": "28",

    "toleranceTarget": "5",

    "tolerancePeriod":{

        "endDateTime": "T12:00:00",

        "startDateTime": "T13:00:00"

    },

    "serviceLevelSpecParameter": {

        "name": "speed",

        "serviceParmCategory": "technology specific",

        "serviceParmPerspective": " single user instance parameter",

        "transformationAlgorithmOfKQI": "KeepTheSame",

        "type": "KPI",

        "validFor":{

            "endDateTime": "2018-03-00T00:00:00",

            "startDateTime": "2016-03-00T00:00:00"

        },

        "relatedPartyRef": {

            "id": "1988",

            "href": "https://host:port/ServiceInventory/service/1988",

            "name": "A service"

        },

    },

    "serviceLevelSpecConsquence": [

        {

            "prescribedAction": "A hyperlink to an action",

            "validFor": {

                "endDateTime": "2018-03-00T00:00:00",

                "startDateTime": "2016-03-00T00:00:00"

            }

        },

        {

            "prescribedAction": "A hyperlink to another action",

            "validFor": {

                "endDateTime": "2018-03-00T00:00:00",

                "startDateTime": "2016-03-00T00:00:00"

            }

        },

    ]

}

 

SERVICE LEVEL SPECIFICATION

A service level specification is a pre-defined or negotiated set of Service Level Objectives, and consequences that occur, if the objectives are not met.

Here is an example of the Service Level Specification:

Messaging Services timely delivery for the day from 00:00 to 23:59 hrs.

Associated SLOs will be:

SMS_Delivery_rate_3mn>90% (SMS delivered 3 minutes should be greater than 90%)

And MMS_Delivery_rate_3mn>90% (MMS delivered 3 minutes should be greater than 90%).

Across one hour period, but do not consider Evening Busy Period from 18:00 to 20:00 hours.

The associated KQIs that can be measured are “Time taken to deliver a SMS or a MMS”.

Resource Model

Fig.2: Service Level Specification

Field descriptions

RelatedServiceLevelObjectiveRef fields

A set of Service Level Objectives that are contained in the Service Level Specification.

href

A String. The hyperlink to access a service level object.

id

A String. The identifier of a service level object.

 

ServiceLevelSpecification fields

A Service Level Specification represents a pre-defined or negotiated set of Service Level Objectives. In addition, certain consequences are associated with not meeting the Service Level Objectives. Service Level Agreements are expressed in terms of Service Level Specifications.

description

A String. A brief introduction of a service level specification.

href

A String. The hyperlink to access a service level specification.

id

A String. The identifier to a service level specification.

name

A string. The name of Service Level Specification

validFor

A time period.

relatedServiceLevelObjectiveRef

A set of Service Level Objectives that are contained in the Service Level Specification.

 

ValidFor fields

A time period.

endDateTime

A DateTime. The end date and time.

startDateTime

A DateTime. The start date and time.

 

JSON representation sample

We provide below the JSON representation of an example of Service Level Specification object: 

 

{

    "href": "https://host:port/SQM/serviceLevelSpecification/1112",

    "id": "1112",

    "description": "This is a service level specification of comunction",

    "name": "SpeedRequirement",

    "validFor": {

        "endDateTime": "2016-05-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

    },

    "relatedServiceLevelObjectiveRef ": [

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3112",

            "id": "3112",

        },

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3113",

            "id": "3113",

        }

    ]

}

 

Notification Resource Models

6 notifications are defined for this API

Notifications related to   Service Level Objective :
    - ServiceLevelObjective CreationNotification

    - ServiceLevelObjectiveAttributeValueChangeNotification

    - ServiceLevelObjectiveRemoveNotification

Notifications related to Service Level Specification:
    - ServiceLevelSpecification CreationNotification
    - ServiceLevelSpecificationAttributeValueChangeNotification
    - ServiceLevelSpecificationRemoveNotification

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).

Service Level Objective Creation Notification

Notification sent when a new Service Level Objective resource is created.

Json representation sample

We provide below the JSON representation of an example of a ' ServiceLevelObjectiveCreationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":" ServiceLevelObjective CreationNotification",
     "event": {
        " serviceLevelObjective " :
            {-- SEE ServiceLevelObjective RESOURCE SAMPLE --}
    }
}
 

Service Level Objective Attribute value change Notification

Notification sent when the value of an attribute is changed.

Json representation sample

We provide below the JSON representation of an example of a ' ServiceLevelObjective AttributeValueChangeNotification' notification object

{
    "eventId":"00002",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":" ServiceLevelObjectiveAttributeValueChangeNotification",
     "event": {
        " serviceLevelObjective " :
            {-- SEE ServiceLevelObjective RESOURCE SAMPLE --}
    }
}
 

Service Level Objective Remove Notification

Notification sent when removing a ServiceLevelObjective resource.

Json representation sample

We provide below the JSON representation of an example of a 'ServiceLevelObjectiveRemoveNotification' notification object

{
    "eventId":"00003",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"ServiceLevelObjectiveRemoveNotification",
     "event": {
        " serviceLevelObjective " :
            {-- SEE ServiceLevelObjective RESOURCE SAMPLE --}
    }
}
 

Service Level Specification Creation Notification

Notification sent when a new ServiceLevelSpecification resource is created.

Json representation sample

We provide below the JSON representation of an example of a 'ServiceLevelSpecificationCreationNotification' notification object

{
    "eventId":"00004",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":" ServiceLevelSpecification CreationNotification",
     "event": {
        " ServiceLevelSpecification" :
            {-- SEE ServiceLevelSpecification RESOURCE SAMPLE --}
    }
}
 

Service Level Specification Attribute value change Notification

Notification sent when the value of an attribute is changed.

Json representation sample

We provide below the JSON representation of an example of a ' ServiceLevelObjectiveAttributeValueChangeNotification' notification object

{
    "eventId":"00002",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":" ServiceLevelObjectiveAttributeValueChangeNotification",
     "event": {
        " serviceLevelObjective " :
            {-- SEE ServiceLevelObjective RESOURCE SAMPLE --}
    }
}
 

Service Level Specification Remove Notification

Notification sent when removing a ServiceLevelObjective resource.

Json representation sample

We provide below the JSON representation of an example of a 'ServiceLevelObjectiveRemoveNotification' notification object

{
    "eventId":"00003",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"ServiceLevelSpecificationRemoveNotification",
     "event": {
        " ServiceLevelSpecification" :
            {-- SEE ServiceLevelSpecification RESOURCE SAMPLE --}
    }
}
 

 

 

API OPERATION

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 Service Level Objective

List Service Level Objective

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

Description

This operation list partnership type entities.
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 ServiceLevelObjective resources.


Request
 

GET /SQM/ serviceLevelObjective ? fields=id,href
Accept: application/json

 


Response
 

200

[

{

    "href": "https://host:port/SQM/serviceLevelObjective/ 3112 ",

    "id": "3112",

},

{

    "href": "https://host:port/SQM/serviceLevelObjective/3112",

    "id": "3113",

}

]
 

Retrieve Service Level Objective

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

Description

This operation retrieves a service level objective entity.
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 an example of a request for retrieving a ServiceLevelObjective resource.


Request
 

GET /SQM/ serviceLevelObjective / 3112?fields=conformancePeriod,graceTimes,serviceLevelSpecParameter


Accept: application/json

 


Response
 

200

{

    "conformancePeriod": {

        "endDateTime": "2017-03-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

    },

    "graceTimes": 3,

    "serviceLevelSpecParameter": {

       "name": "speed",

        "serviceParmCategory": "technology specific",

        "serviceParmPerspective": " single user instance parameter",

        "transformationAlgorithmOfKQI": "KeepTheSame",

        "type": "KPI",

        "validFor":{

            "endDateTime": "2018-03-00T00:00:00",

            "startDateTime": "2016-03-00T00:00:00"

        }

}

Create Service Level Objective

  POST /serviceLevelObjective

Note: this operation is available only to ADMIN API users

Description

This operation creates a service level objective type entity.

Mandatory and Non Mandatory Attributes

The following tables provides the list of mandatory and non mandatory attributes when creating a ServiceLevelObjective, including any possible rule conditions and applicable default values.

Mandatory Attributes

Rule

conformanceTarget

 

conformanceComparator

 

ServiceLevelSpecParameter

 

 

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships when creating a Service violation alarm resource.

Context

Mandatory Sub-Attributes

ServiceLevelSpecParameter

name,relatedEntityRef

RelatedEntityRef

id,href

 

Usage Samples

Here's an example of a request for creating a ServiceLevelObjective resource. In this example the request only passes mandatory attributes.


Request
 

POST /SQM/serviceLevelObjective
Content-Type: application/json

{
       "conformanceTarget" : "5"

"conformanceComparator " : "above"

"serviceLevelSpecParameter": {

        "name": "speed",

        "serviceParmCategory": "technology specific",

        "serviceParmPerspective": " single user instance parameter",

        "transformationAlgorithmOfKQI": "KeepTheSame",

        "type": "KPI",

        "relatedPartyRef": {

            "id": "1988",

            "href": "https://host:port/ServiceInventory/service/1988",

            "name": "A service"

        },

    }
}
 


Response
 

201

{
    "href": "https://host:port/SQM/serviceLevelObjective/3332",

"id": "3332",

"conformanceTarget" : "5"

"conformanceComparator": "above"

"serviceLevelSpecParameter": {

        "name": "speed",

        "serviceParmCategory": "technology specific",

        "serviceParmPerspective": " single user instance parameter",

        "transformationAlgorithmOfKQI": "KeepTheSame",

        "type": "KPI",

        "relatedPartyRef": {

            "id": "1988",

            "href": "https://host:port/ServiceInventory/service/1988",

            "name": "A service"

        },

    }
 

Patch Service Level Objective

  PATCH /serviceLevelObjective/{id}

Note: this operation is available only to ADMIN API users

Description

This operation allows partial updates of a service level objective entity. Support of json/merge (https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is optional.

Note: If the update operation yields to the creation of sub-resources, the same rules concerning mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH operation.  Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their usage.

Patchable Attributes

Rule

conformanceComparator

 

conformanceTarget

The valued could be “above” or “below”.

graceTimes

 

name

 

thresholdTarget

 

toleranceTarget

 

conformancePeriod

 

validFor

 

serviceLevelSpecConsquence

 

tolerancePeriod

 

serviceLevelSpecParameter

 

 

Non Patchable Attributes

Rule

href

 

id

 

 

Usage Samples

Here's an example of a request for patching a ServiceLevelObjective resource.


Request
 

PATCH /SQM/ serviceLevelObjective /3332
Content-Type: application/merge-patch+json

{
    " conformanceTarget": "6"
}

 


Response
 

201

{
        "href": "https://host:port/SQM/serviceLevelObjective/3332",

"id": "3332",

"conformanceTarget" : "6"

"conformanceComparator": "above"

"serviceLevelSpecParameter": {

        "name": "speed",

        "serviceParmCategory": "technology specific",

        "serviceParmPerspective": " single user instance parameter",

        "transformationAlgorithmOfKQI": "KeepTheSame",

        "type": "KPI",

        "relatedPartyRef": {

            "id": "1988",

            "href": "https://host:port/ServiceInventory/service/1988",

            "name": "A service"

        },

}
 

Delete Service Level Objective

  DELETE / serviceLevelObjective /{id}

Note: this operation is available only to ADMIN API users

Description

This operation deletes a serviceLevelObjective type entity.

 

Usage Samples

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


Request
 

DELETE /SQM/serviceLevelObjective /3332

 


Response
 

204

 

Operations on Service Level SPECIFICATION

List Service Level SPECIFICATION

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

Description

This operation list service level specification entities.
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 service level specification resources.


Request
 

GET /SQM/serviceLevelSpecification?fields=id,href,name,validFor
Accept: application/json

 


Response
 

200

[
{

    "href": "https://host:port/SQM/serviceLevelSpecification/1112",

    "id": "1112",

    "name": "SpeedRequirement",

    "validFor": {

        "endDateTime": "2016-05-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

},

{

"href": "https://host:port/SQM/serviceLevelSpecification/1116",

    "id": "1116",

    "name": "SpeedRequirement",

    "validFor": {

        "endDateTime": "2016-05-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

    }

}
]
 

Retrieve Service Level SPECIFICATION

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

Description

This operation retrieves a service level specification entity.
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 an example of a request for retrieving a service level specification resource.


Request
 

/SQM/serviceLevelSpecification/1112?fields=id,href,name,validFor
Accept: application/json

 


Response
 

200

{

    "href": "https://host:port/SQM/serviceLevelSpecification/1112",

    "id": "1112",

    "name": "SpeedRequirement",

    "validFor": {

        "endDateTime": "2016-05-00T00:00:00",

        "startDateTime": "2016-03-00T00:00:00"

}
 

Create Service Level SPECIFICATION

  POST /serviceLevelSpecification

Note: this operation is available only to ADMIN API users

Description

This operation creates service level specification entity.

Mandatory and Non Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a S erviceLevelSpecification , including any possible rule conditions and applicable default values.

Mandatory Attributes

Rule

name

 

relatedServiceLevelObjectiveRef

 

 

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships when creating a service level specification resource.

Context

Mandatory Sub-Attributes

relatedServiceLevelObjectiveRef

id, href

 

Default Values Summary

Usage Samples

Here's an example of a request for creating a serviceLevelSpecification resource. In this example the request only passes mandatory attributes.


Request
 

POST /SQM/ serviceLevelSpecification
Content-Type: application/json

{

    "name": "SpeedRequirement2",

    "relatedServiceLevelObjectiveRef ": [

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3118",

            "id": "3118",

        },

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3117",

            "id": "3117",

        }

    ]

}
 


Response
 

201

{

    "href": "https://host:port/SQM/serviceLevelSpecification/1116",

    "id": "1116",

    "name": "SpeedRequirement2",

    "relatedServiceLevelObjectiveRef ": [

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3118",

            "id": "3118",

        },

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3117",

            "id": "3117",

        }

    ]

}
 

Patch Service Level SPECIFICATION

  PATCH /serviceLevelSpecification/{id}

Description

This operation allows partial updates of a service level specification entity. Support of json/merge (https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH operation.  Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their usage.

Patchable Attributes

Rule

description

 

name

 

validFor

 

relatedServiceLevelObjectiveRef

 

 

Non Patchable Attributes

Rule

href

 

id

 

 

Usage Samples

Here's an example of requests for patching a service level specification resource.

Changing the status to 'prospective' (using json-merge)


Request
 

PATCH /SQM/serviceLevelSpecification/1116
Content-Type: application/merge-patch+json
 

{
    "name": "Changed",

}
 


Response
 

201

{

    "href": "https://host:port/SQM/serviceLevelSpecification/1116",

    "id": "1116",

    "name": "Changed",

    "relatedServiceLevelObjectiveRef ": [

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3118",

            "id": "3118",

        },

        {

            "href": "https://host:port/SQM/serviceLevelObjective/3117",

            "id": "3117",

        }

    ]

}
 

Delete Service Level SPECIFICATION

  DELETE /serviceLevelSpecification/{id}

Note: this operation is available only to ADMIN API users

Description

This operation deletes a party role entity.

 

Usage Samples

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


Request
 

DELETE /SQM/ serviceLevelSpecification /1116

 


Response
 

204

 

 

API NOTIFICATIO NS

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.

 

 

 

Release History

 

Release Number

Date

Release led by:

Description

Release 0.1

23/10/2015

Sanjay Saxena

Pierre Gauthier

First Release of Draft Version of the Document.

Release 0.2

21/07/2016

Sanjay Saxena

Yisong Jiang

Updated for use in the Swagger