Frameworx Specification

Service Inventory
API REST Specification

TMF638
Release 18.0.0
January 2018

Latest Update: TM Forum Release 18.0 Member Evaluation

Version: 2.0.0 IPR Mode: RAND

TM Forum 2018. All Rights Reserved.

Service Inventory API REST Specification

NOTICE
Copyright © TM Forum 2018. All Rights Reserved.

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

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

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

Direct inquiries to the TM Forum office:

4 Century Drive, Suite 100

Parsippany, NJ 07054, USA
Tel No. +1 973 944 5100
Fax No. +1 973 944 5110
TM Forum Web Page: www.tmforum.org

© TM Forum 2018. All Rights Reserved. Page 2

Service Inventory API REST Specification

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

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

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

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

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

Service inventory query for a customer................................................................................................... 7

Service inventory update as part of service provisioning ........................................................................ 7

RESOURCE MODEL ................................................................................................................................. 8

Managed Entity and Task Resource Models .......................................................................................... 8

Service resource.................................................................................................................................. 8

Notification Resource Models ............................................................................................................... 15

Service Creation Notification ............................................................................................................. 16

Service Attribute Value Change Notification ...................................................................................... 16

Service State Change Notification ..................................................................................................... 17

Service Batch Notification .................................................................................................................. 17

Service Remove Notification .............................................................................................................. 18

API OPERATIONS................................................................................................................................... 19

Operations on Service .......................................................................................................................... 19

List services....................................................................................................................................... 20

Retrieve service ................................................................................................................................. 21

Create service ................................................................................................................................... 23

Patch service ..................................................................................................................................... 26

Delete service .................................................................................................................................... 28

API NOTIFICATIONS............................................................................................................................... 29

Register listener ................................................................................................................................... 29

Unregister listener ................................................................................................................................ 30

© TM Forum 2018. All Rights Reserved. Page 3

Service Inventory API REST Specification

Publish Event to listener ....................................................................................................................... 30

Acknowledgements .................................................................................................................................. 32

Release History .................................................................................................................................... 32

© TM Forum 2018. All Rights Reserved. Page 4

Service Inventory API REST Specification

LIST OF TABLES

N/A

© TM Forum 2018. All Rights Reserved. Page 5

Service Inventory API REST Specification

INTRODUCTION
The following document is intended to provide details of the REST API interface for Service Inventory. The
intent of this API is to provide a consistent/standardized mechanism to query and manipulate the Service
inventory.

© TM Forum 2018. All Rights Reserved. Page 6

Service Inventory API REST Specification

SAMPLE USE CASES

Service inventory query for a customer

The Service Inventory API can be used to query the service instances for a customer via Self Service
Portal or the Call Centre operator can query the service instances on behalf of the customer while a
customer may have a complaint or a query.

Note: Only the CustomerFacingServices instances will be presented to the customer.

Service inventory update as part of service provisioning

The Service Inventory API can be called by the Service Order Management to create a new service
instance/ update an existing service instance in the Service Inventory.

© TM Forum 2018. All Rights Reserved. Page 7

Service Inventory API REST Specification

RESOURCE MODEL

Managed Entity and Task Resource Models

SERVICE RESOURCE
Service is an abstract base class for defining the Service hierarchy. All Services are characterized as
either being possibly visible and usable by a Customer or not. This gives rise to the two subclasses of
Service: CustomerFacingService and ResourceFacingService.

Resource model

class Serv ice resource

Serv iceOrderRef Serv iceRef

Place
id :String id :String
id :String href :String href :String
href :String serviceOrderItemId :String
name :String serviceOrder 0..* serviceRef 1
role :String
1
RelatedPartyRef @referredType :String

place Serv iceRelationship

id :String 0..*
href :String serviceRelationship type :String
role :String
name :String 0..*
validFor :TimePeriod 0..1 0..1
relatedParty
@referredType :String
1..* 1..* Serv ice

id :String
Note note
href :String
0..1
date :DateTime 0..* 0..1 name :String
author :String description :String
text :String type :String
state :String
category :String Serv iceCharacteristic
isServiceEnabled :boolean characteristic
name :String
hasStarted :boolean
startMode :String 1 0..* valueType :String
isStateful :boolean
serviceDate :DateTime
Serv iceSpecificationRef startDate :DateTime
serviceSpecification 0..1
endDate :DateTime
id :String
href :String 0..1 0..1 @type :String
@baseType :String 0..* value 0..1
name :String A
@schemaLocation :String
version :String Value
@type :String 0..*
@schemaLocation :String @type :String
@baseType :String @schemaLocation :String

0..1

0..1 targetServiceSchema
supportingResource 0..* supportingService 0..*

TargetServ iceSchema SupportingResource SupportingServ ice

@type :String id :String id :String

@schemaLocation :String href :String href :String
role :String name :String
name :String category :String
@referredType :String @referredType :String

© TM Forum 2018. All Rights Reserved. Page 8

Service Inventory API REST Specification

Lifecycle

Here is the state machine diagram for a Service.

Field descriptions

Service fields

Field Description
id A string. "id" is the ID created for the service.
href A string. Reference of the service.
name A string. "name" is the name of the service.
description A string. free-text description of the service.
type A string; Type of the service – could for example CFS, RFS, compositeCFS,
atomicCFS, compositeRFS, atomicRFS, etc…
state A string. The life cycle state of the service:
- feasibilityChecked
- designed
- reserved
- active
- inactive
- terminated
category A string. Is it a customer facing or resource facing service.
isServiceEnabled A boolean. For use. If the value of this attribute is FALSE, then this means that
this particular Service has NOT been enabled for use.
hasStarted A boolean. This is a Boolean attribute that, if TRUE, signifies that this Service
has already been started. If the value of this attribute is FALSE, then this
signifies that this Service has NOT been Started.

© TM Forum 2018. All Rights Reserved. Page 9

Service Inventory API REST Specification

startMode A string. This attribute is an enumerated integer that indicates how the Service
is started. Values include:
0: Unknown
1: Automatically by the managed environment
2: Automatically by the owning device
3: Manually by the Provider of the Service
4: Manually by a Customer of the Provider
5: Any of the above.
isStateful A boolean. This is a Boolean attribute that, if TRUE, means that this Service
can be changed without affecting any other services.
serviceDate A date time (DateTime). Date when the service was created (whatever its
status).
startDate A date time (DateTime). startDate is the date when the service starts 
meaning it shifts to ‘active’ status (the first time).
endDate A date time (DateTime). endDate is the date when the service ends 
meaning it shifts to ‘terminated’ status
@baseType A string. Indicates the base type of the resource. Here it should be valued to
Service.
@type A string. Indicates the type of resource..
@schemaLocation A string. A link to the schema describing this REST resource.
serviceOrder A list of service order reference (ServiceOrderRef). A Service Order is a
request to perform an action on a specific Service and it contained service
order item.
serviceRelationship A list of service relationships (ServiceRelationship [*]). Describes links with
other service(s) in the inventory (useful for describing relies-on, relies-from
between CFS for example).
characteristic A list of service characteristics (ServiceCharacteristic [*]).
supportingService A list of supporting services (SupportingService [*]). A collection of services
that support this service (bundling, link CFS to RFS).
supportingResource A list of supporting resources (SupportingResource [*]).Note: only Service of
type RFS can be associated with Resources.
serviceSpecification A service specification reference (ServiceSpecificationRef).
ServiceSpecification(s) required realizing a ProductSpecification.
place A list of places (Place [*]). Used to define a place useful for the service (for
example a delivery geographical place).
note A list of notes (Note [*]). Extra information about the service.
relatedParty A list of related party references (RelatedPartyRef [1..*]). A related party
defines party or party role linked to a specific entity.

Note sub-resource

Extra information about the service.

Field Description
author A string. Author of the note.
date A date time (DateTime). Date of the note.
text A string. Text of the note.

Place

© TM Forum 2018. All Rights Reserved. Page 10

Service Inventory API REST Specification

Used to define a place of interest for the service (for example installation address).

Field Description
id A string. ID of an existing place
href A string. Reference of a place (for instance in google map).
role A string. The role of the place (e.g. install site, a-address, z-address for leased
line, geoFencing perimeter).
@referredType A string. The type of the referred appointment

ServiceCharacteristic

Structure to describe the characteristics of the service.

Field Description
name A string. Name of the characteristic.
valueType A string. Value type of the characteristic. Could a simple attribute or a complex
one as a table or an array.
value A string. A link to a value description structure.

Value

Structure to describe the Characteristic value of the service.

Field Description
@type A string. Indicates the (class) type of resource.
@schemaLocation A string. This field provided a link to the schema describing this REST
resource.

ServiceRelationship sub-resource

Describes links with services of the same category (useful for relies-on, relies-from relationships between
services).

Field Description
type A string. Describes links with services of the same category (useful for bundled
services, or to describe relies On relationship between services for example).
serviceRef A service reference (ServiceRef). Useful to link services of the same category.

ServiceRef relationship

Service reference. Useful to link services.

Field Description
href A string. reference of the service.
id A string. Id of the service.

SupportingResource sub-resource

© TM Forum 2018. All Rights Reserved. Page 11

Service Inventory API REST Specification

A collection of resource(s) supporting the service. – Note: only Service of type RFS can be associated
with Resources.

Field Description
href A string. Reference of the supporting resource.
id A string. Unique identifier of the supporting resource.
role A string. Role of the supporting resource
name A string. Name of the resource supporting the service.
@referredTypa A string; Type of the resource.

SupportingService sub-resource

A collection of services that support this service -This could be used to described

• service bundling (composite/atomic) for CFS as RFS

• relationship from CFS to list supporting RFS

Field Description
href A string. Reference of the supporting service.
id A string. Unique identifier of the supporting service.
category A string. Category of the supporting service.
name A string. Name of the supporting service.
@referredType A string; Type of the resource.

RelatedPartyRef relationship

RelatedParty reference. A related party defines party or party role linked to a specific entity.

Field Description
href A string. Reference of the related party, could be a party reference or a party
role reference.
id A string. Unique identifier of a related party.
name A string. Name of the related party.
role A string. Role of the related party.
validFrom A timePeriod – Period of time when this party is relevant
@referredType A string; Type of the party.

ServiceOrderRef relationship

A Service Order is a request to perform an action on a specific Service.

Field Description
href A string. The Hyperlink to access the related Service Order.
id A string. Unique identifier of the related Service Order.
serviceOrderItemId A string. Id of the service order creating/modifying this service

ServiceSpecification relationship

© TM Forum 2018. All Rights Reserved. Page 12

Service Inventory API REST Specification

Service specification reference is a class that offers characteristics to describe service.

Field Description
id A string. Unique identifier of the service specification.
href A string. Reference of the service specification.
version A string. Version of the service specification.
name A string. Name of the service specification.
@type A string. Indicates the (class) type of resource (here service specification).
@schemaLocation A string. URL to get to the schema description file.
@baseType A string. Indicates the base type of the sub resource. Here it should be valued
to 'ServiceSpecification'.

TargetServiceSchema sub-resource

Target to the schema describing the service spec resource (and type)

Field Description
@type A string. Indicates the (class) type of resource.
@schemaLocation A string. This field provided a link to the schema describing this REST
resource.

Json representation sample

We provide below the json representation of an example of a 'Service' resource object

{
"id":"11",
"href":"http://..../service/11",
"name":"NiceService",
"description":"Service inventory sample",
"@type":"vCPE",
"state":"Active",
"type":"CFS",
"category":"Cloud",
"isServiceEnabled":true,
"hasStarted":true,
"startMode":"1",
"isStateful":true,
"serviceDate":"2018-01-15T12:26:11.747Z",
"startDate":"2018-01-15T12:26:11.747Z",
"serviceSpecification":{
"id":"12",
"href":"http://...:serviceSpecification/12",
"name":"vCPE",
"version":"1",
"@type":"vCPE",
"@schemaLocation":"http..."
},
"serviceCharacteristic":[
{
"name":"vCPE_IP",

© TM Forum 2018. All Rights Reserved. Page 13

Service Inventory API REST Specification

"valueType":"String",
"value":{
"@type":"IPAddress",
"@schemaLocation":"http....",
"vCPE_IP":"193.218.236.21"
}
}
],
"serviceRelationship":[
{
"type":"ReliesOn",
"service":{
"id":"19",
"href":"http://..../service/19"
}
}
],
"supportingService":[
{
"id":"17",
"href":"http://..../service/17",
"name":"supporting service vxwn",
"@referredType":"vxwn"
}
],
"supportingResource":[
{
"id":"99",
"href":"http://..../resource/99",
"name":"GenInfra",
"@referredType":"Infra"
},
{
"id":"94",
"href":"http://..../resource/94",
"name":"BNG_MUX",
"@referredType":"MUX"
}
],
"relatedParty":[
{
"id":"456",
"href":"http://serverlocation:port/partyManagement/party/456",
"role":"user"
}
],
"serviceOrder":[
{
"id":"42",
"href":"http://serverlocation:port/orderManagement/serviceOrder/42",
"serviceOrderItem":"1"
}
],
"note":[

© TM Forum 2018. All Rights Reserved. Page 14

Service Inventory API REST Specification

{
"date":"2018-01-15T12:26:11.748Z",
"author":"Jean Pontus",
"text":"bla bla bla"
}
]
}

Notification Resource Models

5 notifications are defined for this API

Notifications related to Service:

- ServiceCreationNotification
- ServiceAttributeValueChangeNotification
- ServiceStateChangeNotification
- ServiceBatchNotification
- ServiceRemoveNotification

The notification structure for all notifications in this API follows 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 occurrence (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).

© TM Forum 2018. All Rights Reserved. Page 15

Service Inventory API REST Specification

SERVICE CREATION NOTIFICATION

Notification sent when a new Service resource is created.

Json representation sample

We provide below the json representation of an example of a 'ServiceCreationNotification' notification

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ServiceCreationNotification",
"event": {
"service" :
{-- SEE Service RESOURCE SAMPLE --}
}
}

SERVICE ATTRIBUTE VALUE CHANGE NOTIFICATION

© TM Forum 2018. All Rights Reserved. Page 16

Service Inventory API REST Specification

Notification sent when changing an attribute of a Service resource.

Json representation sample

We provide below the json representation of an example of a 'ServiceAttributeValueChangeNotification'

notification object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ServiceAttributeValueChangeNotification",
"event": {
"service" :
{-- SEE Service RESOURCE SAMPLE --}
}
}

SERVICE STATE CHANGE NOTIFICATION

Notification sent when changing the state of a Service resource.

Json representation sample

We provide below the json representation of an example of a 'ServiceStateChangeNotification' notification

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ServiceStateChangeNotification",
"event": {
"service" :
{-- SEE Service RESOURCE SAMPLE --}
}
}

SERVICE BATCH NOTIFICATION

Notification sent when a batch job on resource Service changes

Json representation sample

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

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ServiceBatchNotification",
"event": {
"service" :

© TM Forum 2018. All Rights Reserved. Page 17

Service Inventory API REST Specification

{-- SEE Service RESOURCE SAMPLE --}

}
}

SERVICE REMOVE NOTIFICATION

Notification sent when removing a Service resource.

Json representation sample

We provide below the json representation of an example of a 'ServiceRemoveNotification' notification

object

{
"eventId":"00001",
"eventTime":"2015-11-16T16:42:25-04:00",
"eventType":"ServiceRemoveNotification",
"event": {
"service" :
{-- SEE Service RESOURCE SAMPLE --}
}
}

© TM Forum 2018. All Rights Reserved. Page 18

Service Inventory API REST Specification

API OPERATIONS

Remember the following Uniform Contract:

Operation on Entities Uniform API Operation Description

Query Entities GET Resource GET must be used to

retrieve a representation of
a resource.

Create Entity POST Resource POST must be used to

create a new resource

Partial Update of an Entity PATCH Resource PATCH must be used to

partially update a resource

Complete Update of an 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 Resource POST must be used to

Entity 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

© TM Forum 2018. All Rights Reserved. Page 19

Service Inventory API REST Specification

LIST SERVICES
GET /service?fields=...&{filtering}
Description

This operation lists service entity(ies).

Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Providing filtering criteria is mandatory to avoid too many answers retrieved. See example below:

• description
• relatedParty.id
• category + state
• type + date selection
• supportingResource.id

Usage Samples

Here's an example of a request for retrieving Service resources.

Get all RFS supported by a specific resource

Request

GET /serviceInventoryManagement/service?fields=id,category,name,state&category=RFS&description= Service

inventory sample
Accept: application/json

Response

200

[
{
"id":"11",
"name":"NiceService",
"@type":"vCPE",
"state":"Active",
"category":"Cloud"
},

© TM Forum 2018. All Rights Reserved. Page 20

Service Inventory API REST Specification

{
"id":"196",
"name":"NiceServiceToo",
"@type":"vCPE",
"state":"Active",
"category":"Cloud"
},
{
"id":"88",
"name":"NiceServiceAsWell",
"@type":"Firewall",
"state":"Inactive",
"category":"Cloud"
}
]

RETRIEVE SERVICE
GET /service/{id}?fields=...&{filtering}
Description

This operation retrieves a service 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 resource.

Request

GET /serviceInventoryManagement/service/11
Accept: application/json

Response

200

{
"id":"11",
"href":"http://..../service/11",
"name":"NiceService",
"description":"Service inventory sample",

© TM Forum 2018. All Rights Reserved. Page 21

Service Inventory API REST Specification

"@type":"vCPE",
"state":"feasibilityChecked",
"category":"Cloud",
"isServiceEnabled":true,
"hasStarted":true,
"startMode":"1",
"isStateful":true,
"serviceDate":"2018-01-15T12:26:11.747Z",
"startDate":"2018-01-15T12:26:11.747Z",
"serviceSpecification":{
"id":"12",
"href":"http://...:serviceSpecification/12",
"name":"vCPE",
"version":"1",
"@type":"vCPE",
"@schemaLocation":"http..."
},
"serviceCharacteristic":[
{
"name":"vCPE_IP",
"valueType":"String",
"value":{
"@type":"IPAddress",
"@schemaLocation":"http....",
"vCPE_IP":"193.218.236.21"
}
}
],
"serviceRelationship":[
{
"type":"ReliesOn",
"service":{
"id":"19",
"href":"http://..../service/19"
}
}
],
"supportingService":[
{
"id":"17",
"href":"http://..../service/17",
"name":"supporting service vxwn",
"@referredType":"vxwn"
}
],
"supportingResource":[
{
"id":"99",
"href":"http://..../resource/99",
"name":"GenInfra",
"@referredType":"Infra"
},
{
"id":"94",

© TM Forum 2018. All Rights Reserved. Page 22

Service Inventory API REST Specification

"href":"http://..../resource/94",
"name":"BNG_MUX",
"@referredType":"MUX"
}
],
"relatedParty":[
{
"id":"456",
"href":"http://serverlocation:port/partyManagement/party/456",
"role":"user"
}
],
"serviceOrder":[
{
"id":"42",
"href":"http://serverlocation:port/orderManagement/serviceOrder/42",
"serviceOrderItem":"1"
}
],
"note":[
{
"date":"2018-01-15T12:26:11.748Z",
"author":"Jean Pontus",
"text":"bla bla bla"
}
]
}

CREATE SERVICE
POST /service
Note: this operation is available only to ADMIN API users

Description

This operation creates a service entity.

Mandatory and Non Mandatory Attributes

POST request should be used without specifying following attributes (these attributes will be defined by
server side):

• id
• href

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

© TM Forum 2018. All Rights Reserved. Page 23

Service Inventory API REST Specification

Mandatory Attributes Rule

state
serviceSpecification.id

if serviceOrder is provided (id AND/OR href) is required

if RelatedPartyRef is provided (id AND/OR href AND/OR name) and role are required
if Place is provided (id AND/OR href) and role are required
if ServiceSpecificationRef is (id AND/OR href) is required
provided
if Note is provided date, author and text are required
if ServiceRelationship is type and service (ref or value) are required
provided
if ServiceCharacteristic is name, valueType and value are required
provided

Non Mandatory Attributes Default Value Rule

category
description
endDate blank
hasStarted No
isServiceEnabled
isStateful Yes
serviceDate Today
startDate Today
startMode
type
serviceOrder Structure could be not present
supportingResource Structure could be not present
serviceRelationship Structure could be not present
place Structure could be not present
supportingService Structure could be not present
note Structure could be not present
serviceSpecification Structure could be not present
relatedParty Structure could be not present
characteristic Structure could be not present
serviceOrder Structure could be not present

Additional Rules

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

Context Mandatory Sub-Attributes

serviceOrder id, href
serviceSpecification id, href
relatedParty role, id or href
serviceRelationship type, Id OR href

© TM Forum 2018. All Rights Reserved. Page 24

Service Inventory API REST Specification

Context Mandatory Sub-Attributes

supportingService id, href
supportingResource id, href
note text
place role, id or href

Usage Samples

Here's an example of a request for creating a Service resource.

Create a CFS service in the inventory

Request

{
"name":"NiceService",
"description":"Service inventory sample",
"@type":"vCPE",
"state":"Active",
"category":"Cloud",
"isServiceEnabled":true,
"hasStarted":true,
"startMode":"1",
"isStateful":true,
"serviceSpecification":{
"id":"12",
"href":"http://...:serviceSpecification/12",
"name":"vCPE",
"version":"1",
"@type":"vCPE",
"@schemaLocation":"http..."
},
"serviceCharacteristic":[
{
"name":"vCPE_IP",
"valueType":"String",
"value":{
"@type":"IPAddress",
"@schemaLocation":"http....",
"vCPE_IP":"193.218.236.21"
}
}
],
"serviceRelationship":[
{
"type":"ReliesOn",
"service":{
"id":"19",
"href":"http://..../service/19"
}
}
],

© TM Forum 2018. All Rights Reserved. Page 25

Service Inventory API REST Specification

"relatedParty":[
{
"id":"456",
"href":"http://serverlocation:port/partyManagement/party/456",
"role":"user"
}
],
"note":[
{
"date":"2018-01-15T12:26:11.748Z",
"author":"Jean Pontus",
"text":"bla bla bla"
}
]
}

Response

201

"{ JSON Resource Representation with every provided and default attribute}"

PATCH SERVICE
PATCH /service/{id}
Note: this operation is available only to ADMIN API users

Description

This operation allows partial updates of a service 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes Rule

category
description
endDate

© TM Forum 2018. All Rights Reserved. Page 26

Service Inventory API REST Specification

Patchable Attributes Rule

hasStarted
isServiceEnabled
isStateful
name
startDate
startMode
state
type
serviceOrder
supportingResource
serviceRelationship
place
supportingService
note
relatedParty
characteristic
orderState

Non Patchable Attributes Rule

id
href
serviceSpecification

Usage Samples

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

Changing the service state (using json-patch)

Request

PATCH /serviceInventoryManagement/service/42
Content-Type: application/json-patch+json

{
"path": "/state",
"value": "reserved",
"op": "replace"
}

Response

201

{ Similar JSON as in GET response with state changed}

© TM Forum 2018. All Rights Reserved. Page 27

Service Inventory API REST Specification

DELETE SERVICE
DELETE /service/{id}
Note: this operation is available only to ADMIN API users

Description

This operation deletes a service entity.

Usage Samples

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

Request

DELETE /serviceInventoryManagement/service/42

Response

204

© TM Forum 2018. All Rights Reserved. Page 28

Service Inventory API REST Specification

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

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

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

© TM Forum 2018. All Rights Reserved. Page 29

Service Inventory API REST Specification

UNREGISTER LISTENER

DELETE /hub/{id}
Description

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

Behavior

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

Return 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/event
Description

Provide 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

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

© TM Forum 2018. All Rights Reserved. Page 30

Service Inventory API REST Specification

Request

POST /event
Accept: application/json

{
"eventId": "12368",
"eventTime": "2018-01-12T13:23:43.704Z",
"eventType": " ServiceStateChangeNotification ",
"event": {
"resource": "48"
}
}

Response

201

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

© TM Forum 2018. All Rights Reserved. Page 31

Service Inventory API REST Specification

ACKNOWLEDGEMENTS

RELEASE HISTORY

Release Date Release led by: Description

Number

Release 16.5 15-Apr-2016 Pierre Gauthier Generated using the API

TM Forum data model
Version 1.0.0 [email protected]

Nicoleta Stoica
Vodafone
[email protected]

Mariano Belaunde
Orange Labs

Release 18.0 31-Jan-2018 Pierre Gauthier Alignment with TMF open

TM Forum API guidelines 3.0
Version 2.0.0 [email protected]
Review with SID Team
Ludovic Robert (Cécile Ludwichowski)
Orange
[email protected]

© TM Forum 2018. All Rights Reserved. Page 32