SQM API REST SPECIFCATION

Service Quality Management

API REST SPECIFICATION
Document Number: <###>
Document Version: : <V0.2>
Date: July, 2016
Document Status: Draft

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 1

SQM API REST SPECIFCATION

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 – 10th 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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 2

SQM API REST SPECIFCATION

TABLE OF CONTENTS
NOTICE ............................................................................................................................................................................ 2

Table of Contents .............................................................................................................................................................. 3

List of Tables .................................................................................................................................................................... 5

Introduction ....................................................................................................................................................................... 6

SAMPLE USE CASES ..................................................................................................................................................... 7

Sample Use Cases ................................................................................................................................................. 7

Resource model ............................................................................................................................................................... 11

Managed Entity and Task Resource Models ...................................................................................................... 11

Service Level Objective Resource .................................................................................................................. 11

Service Level Specification ............................................................................................................................ 14

Notification Resource Models ............................................................................................................................ 16

Service Level Objective Creation Notification ............................................................................................... 17

Service Level Objective Attribute value change Notification ........................................................................ 18

Service Level Objective Remove Notification ............................................................................................... 18

Service Level Specification Creation Notification ......................................................................................... 18

Service Level Specification Remove Notification .......................................................................................... 19

API OPERATION ........................................................................................................................................................... 20

Operations on Service Level Objective .............................................................................................................. 20

List Service Level Objective ........................................................................................................................... 20

Retrieve Service Level Objective ................................................................................................................... 21

Create Service Level Objective ....................................................................................................................... 22

Patch Service Level Objective ........................................................................................................................ 24

Delete Service Level Objective ....................................................................................................................... 25

Operations on Service Level SPECIFICATION ................................................................................................ 26

List Service Level SPECIFICATION ............................................................................................................. 26

Retrieve Service Level SPECIFICATION ..................................................................................................... 26

Create Service Level SPECIFICATION ......................................................................................................... 27

Patch Service Level SPECIFICATION .......................................................................................................... 28

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 3

SQM API REST SPECIFCATION

Delete Service Level SPECIFICATION ......................................................................................................... 30

API NOTIFICATIONS ................................................................................................................................................... 31

Register listener .................................................................................................................................................. 31

Unregister listener ............................................................................................................................................... 31

Publish Event to listener ..................................................................................................................................... 32

Release History ............................................................................................................................................................... 34

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 4

SQM API REST SPECIFCATION

LIST OF TABLES

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 5

SQM API REST SPECIFCATION

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.

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 6

SQM API REST SPECIFCATION

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 I. 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
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 7
SQM API REST SPECIFCATION

notification is misleading ‘Ignore Notifications for this

period, due to Routine Maintenance’
II. 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
III. 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
IV. 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.
V. 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 i. SLAs between Enterprise and Service Provider have been agreed
and defined, which represents contractual agreement between
parties for quality of specific services
ii. 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
iii. SLOs representing actual thresholds to be monitored have been
defined
iv. SLOs have been mapped to Key Quality Indicators for the
services monitored by the Service Quality Management
application
v. 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
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 8
SQM API REST SPECIFCATION

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 i. The Client sends request for Active and Cleared Alarms
ii. The SQM Application validates the request
iii. The SQM Application prepares the list of all active and cleared
alarms
iv. 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:
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 9
SQM API REST SPECIFCATION

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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 10

SQM API REST SPECIFCATION

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
RelatedEntityRef

+ herf: String
+ id: String
+ name: String
1..* ConformancePeriod
Serv iecLev elObj ectiv e
+ endDateTime: DateTime
1 + conformanceComparator: String + startDateTime: DateTime
+ conformanceTarget: String
Serv iceLev elSpecParameter 0..1
+ graceTimes: int 1
+ href: String
+ name: String
+ id: String
+ serviceParmCategory: String
+ serviceParmPerspective: String 1 1 + name: String
+ thresholdTarget: String
+ transformationAlgorithmOfKQI: String 1
+ toleranceTarget: String 0..1 TolerancePeriod
+ type: String
1 1 + endDateTime: DateTime
1 + startDateTime: DateTime

0..1
0..1

0..*
ValidFor
Serv iceLev elSpecConsquence
+ endDateTime: DateTime
+ startDateTime: DateTime + prescribedAction: String
0..1 1

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.

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 11

SQM API REST SPECIFCATION

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
serviceParmPerspectiv A String. A string that specifies whether the Service Level Specification
e Parameter represents a single user instance parameter or a parameter that
represents an aggregation.
transformationAlgorit A String. The description of a logical step-by-step procedure used to
hmOfKQI 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.
conformanceComparat A String. An operator that specifies whether a Service Level Objective is
or 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.
serviceLevelSpecCons Some consequences for the provider of the Service are resulted when the
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 12
SQM API REST SPECIFCATION

quence service level objective does not meet.

tolerancePeriod An interval of time over which the tolerance Target is acceptable before
indication of an objective violation.
serviceLevelSpecPara Service Level Specification parameters can be one of two types. A Key
meter 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"

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 13

SQM API REST SPECIFCATION

},
},
"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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 14

SQM API REST SPECIFCATION

Serv iceLev elSpecification

ValidFor
+ description: String
+ endDateTime: DateTime + href: String
+ startDateTime: DateTime 0..1 1 + id: String
+ name: string

1..*

RelatedServ iceLev elObj ectiv eRef

+ href: String
+ id: String

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.
relatedServiceLevelObje A set of Service Level Objectives that are contained in the Service Level
ctiveRef 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",

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 15

SQM API REST SPECIFCATION

"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:
- ServiceLevelObjectiveCreationNotification
- ServiceLevelObjectiveAttributeValueChangeNotification
- ServiceLevelObjectiveRemoveNotification
Notifications related to Service Level Specification:
- ServiceLevelSpecificationCreationNotification
- 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).

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 16

SQM API REST SPECIFCATION

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":" ServiceLevelObjectiveCreationNotification",
"event": {
" serviceLevelObjective " :
{-- SEE ServiceLevelObjective RESOURCE SAMPLE --}
}
}
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 17
SQM API REST SPECIFCATION

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 '
ServiceLevelObjectiveAttributeValueChangeNotification' 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":"ServiceLevelSpecificationCreationNotification",
"event": {
" ServiceLevelSpecification" :
{-- SEE ServiceLevelSpecification RESOURCE SAMPLE --}
}
}

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 18

SQM API REST SPECIFCATION

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 --}
}
}

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 19

SQM API REST SPECIFCATION

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 PATCH Resource PATCH must be used to

Entity partially update a resource

Complete Update of an PUT Resource PUT must be used to

Entity 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 POST on TASK POST must be used to

Entity Resource execute Task Resources

Other Request Methods POST on TASK GET and POST must not
Resource 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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 20
SQM API REST SPECIFCATION

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
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 21
SQM API REST SPECIFCATION

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

r

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.
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 22
SQM API REST SPECIFCATION

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",

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 23

SQM API REST SPECIFCATION

"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"
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 24
SQM API REST SPECIFCATION

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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 25

SQM API REST SPECIFCATION

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}
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 26
SQM API REST SPECIFCATION

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
ServiceLevelSpecification, including any possible rule conditions and applicable default values.

Mandatory Attributes Rule

name
relatedServiceLevelObjectiveRef

Additional Rules

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 27

SQM API REST SPECIFCATION

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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 28
SQM API REST SPECIFCATION

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",

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 29

SQM API REST SPECIFCATION

},
{
"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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 30

SQM API REST SPECIFCATION

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}

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 31

SQM API REST SPECIFCATION

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
<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 32
SQM API REST SPECIFCATION

},
"eventType": "EVENT_TYPE"
}

Response

201

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

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 33

SQM API REST SPECIFCATION

RELEASE HISTORY

Release Number Date Release led by: Description

Release 0.1 23/10/2015 Sanjay Saxena First Release of Draft Version of the
Pierre Gauthier Document.
Release 0.2 21/07/2016 Sanjay Saxena Updated for use in the Swagger
Yisong Jiang

<Document #, Version 0.2> © TM Forum 2013. All Rights Reserved. Page 34