TM Forum Specification

Service Inventory API REST

Specification

TMF638
Release 18.5.0
January 2019

Latest Update: TM Forum Release 18.5.0 Member Evaluation

Version 4.0.0 IPR Mode: RAND

TM Forum 2019. All Rights Reserved.

TMF638 Service Inventory API REST Specification

NOTICE
Copyright © TM Forum 2019. 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 998 7916
TM Forum Web Page: [Link]

© TM Forum 2019. All Rights Reserved Page 2 of 34

TMF638 Service Inventory API REST Specification

Table of Contents
NOTICE ............................................................................................................................................................................ 2
Table of Contents............................................................................................................................................................ 3
List of Tables ................................................................................................................................................................... 4
Introduction .................................................................................................................................................................... 5
SAMPLE USE CASES ......................................................................................................................................................... 6
Service inventory query for a customer ................................................................................................................ 6
Service inventory update as part of service provisioning................................................................................... 6
Lifecycle of Service .................................................................................................................................................. 6
Support of polymorphism and extension patterns ........................................................................................................ 7
RESOURCE MODEL .......................................................................................................................................................... 8
Managed Entity and Task Resource Models ....................................................................................................... 8
Service resource ...................................................................................................................................................... 8
Notification Resource Models .............................................................................................................................. 14
Service Create Notification.................................................................................................................................... 15
Service Attribute Value Change Notification......................................................................................................... 15
Service State Change Notification ......................................................................................................................... 16
Service Batch Notification ..................................................................................................................................... 16
Service Delete Notification .................................................................................................................................... 17
API OPERATIONS ........................................................................................................................................................... 18
Operations on Service ............................................................................................................................................... 19
List services............................................................................................................................................................ 19
Retrieve service ..................................................................................................................................................... 19
Create service ........................................................................................................................................................ 22
Patch service.......................................................................................................................................................... 26
Delete service ........................................................................................................................................................ 30
API NOTIFICATIONS....................................................................................................................................................... 31
Register listener ........................................................................................................................................................ 31
Unregister listener .................................................................................................................................................... 32
Publish Event to listener ........................................................................................................................................... 32
Acknowledgements ...................................................................................................................................................... 34
Release History ......................................................................................................................................................... 34
Contributors to Document........................................................................................................................................ 34

© TM Forum 2019. All Rights Reserved Page 3 of 34

TMF638 Service Inventory API REST Specification

List of Tables

N/A

© TM Forum 2019. All Rights Reserved Page 4 of 34

TMF638 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 2019. All Rights Reserved Page 5 of 34

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

Lifecycle of Service
Here is the state machine diagram for a Service.

© TM Forum 2019. All Rights Reserved Page 6 of 34

TMF638 Service Inventory API REST Specification

Support of polymorphism and extension patterns

Support of polymorphic collections and types and schema based extension is provided by means of a list of generic
meta-attributes that we describe below. Polymorphism in collections occurs when entities inherit from base
entities, for instance a TypeAService or TypeBService inheriting properties from the base Service entity.

Generic support of polymorphism and pattern extensions is described in the TMF API Guidelines v3.0 Part 2
document.

The @type attribute provides a way to represent the actual class type of an entity. For example, within a list of
Service instances some may be instances of TypeAService where other could be instances of TypeBService. The
@type gives this information. All resources and sub-resources of this API have a @type attributes that can be
provided when this is useful.

The @referredType can be used within reference entities (like for instance an RelatedParty object) to explicitly
denote the actual entity type of the referred class. Notice that in reference entities the @type, when used, denotes
the class type of the reference itself, such as RelatedParty, and not the class type of the referred object. However
since reference classes are rarely sub-classed, @type is generally not useful in reference objects.

The @schemaLocation property can be used in resources to allow specifying user-defined properties of an Entity or
to specify the expected characteristics of an entity.

The @baseType attribute gives a way to provide explicitly the base of class of a given resource that has been
extended.

© TM Forum 2019. All Rights Reserved Page 7 of 34

TMF638 Service Inventory API REST Specification

RESOURCE MODEL
Managed Entity and Task Resource Models

Service resource
Service is a 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

Field descriptions

Service fields

category A string. Is it a customer facing or resource facing service.

description A string. Free-text description of the service.

endDate A date time (DateTime). Date when the service ends.

hasStarted A boolean. If TRUE, this Service has already been started.

href A string. Reference of the service.

id A string. Unique identifier of the service.

isServiceEnabled A boolean. If FALSE, this particular Service has NOT been enabled for use.

isStateful A boolean. If TRUE, this Service can be changed without affecting any other services.

name A string. Name of the service.

© TM Forum 2019. All Rights Reserved Page 8 of 34

TMF638 Service Inventory API REST Specification

note A list of notes (Note [*]). A list of notes made on this service.

place A list of places (Place [*]). A list of places related to this service, e.g. where the service
is installed, a delivery address for equipment, etc.

relatedParty A list of related parties (RelatedParty [*]). A list of related party references
(RelatedParty [1..*]). A related party defines party or party role linked to a specific
entity.

serviceCharacteristic A list of characteristics (Characteristic [*]). A list of characteristics that characterize

this service (ServiceCharacteristic [*]).

serviceDate A string. Date when the service was created (whatever its status).

serviceOrder A list of service order references (ServiceOrderRef [*]). A list of service orders related
to this service.

serviceRelationship A list of service relationships (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).

serviceSpecification A service specification reference (ServiceSpecificationRef). The specification from

which this service was instantiated.

serviceType A string. Business type of the service.

startDate A date time (DateTime). Date when the service starts.

startMode A string. This attribute is an enumerated integer that indicates how the Service is
started, such as: 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.

state A service state type (ServiceStateType). The life cycle state of the service, such as:
feasibilityChecked, designed, reserved, active, inactive, terminated.

supportingResource A list of resource references (ResourceRef [*]). A list of supporting resources

(SupportingResource [*]).Note: only Service of type RFS can be associated with
Resources.

supportingService A list of service references (ServiceRef [*]). A list of supporting services

(SupportingService [*]). A collection of services that support this service (bundling,
link CFS to RFS).

Characteristic sub-resource

Describes a given characteristic of an object or entity through a name/value pair.

name A string. Name of the characteristic.

© TM Forum 2019. All Rights Reserved Page 9 of 34

TMF638 Service Inventory API REST Specification

value An any (Any). The value of the characteristic.

valueType A string. Data type of the value of the characteristic.

Note sub-resource

Extra information about a given entity.

author A string. Author of the note.

date A date time (DateTime). Date of the note.

system A string. Describes the system from which the action related to this note was done.

text A string. Text of the note.

Place sub-resource

Place reference. Place defines the places where the products are sold or delivered.

href A string. Unique reference of the place.

id A string. Unique identifier of the place.

name A string. A user-friendly name for the place, such as [Paris Store], [London Store],
[Main Home].

role A string. Role of the place, such as: [home delivery], [shop retrieval]).

RelatedParty sub-resource

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

@baseType A string. When sub-classing, this defines the super-class.

@referredType A string. The actual type of the target instance when needed for disambiguation.

@schemaLocation A string. A URI to a JSON-Schema file that defines additional attributes and
relationships.

@type A string. When sub-classing, this defines the sub-class entity name.

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.

ServiceRelationship sub-resource

© TM Forum 2019. All Rights Reserved Page 10 of 34

TMF638 Service Inventory API REST Specification

Describes links with services of the same category (useful for bundled services).

relationshipType A string. The type of relationship (e.g. depends on, enables).

service A service reference (ServiceRef). The service being referred to.

TargetServiceSchema sub-resource

The reference object to the schema and type of target service which is described by service specification.

@schemaLocation A string. This field provides a link to the schema describing the target service.

@type A string. Class type of the target service.

ResourceRef relationship

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the supporting resource.

id A string. Unique identifier of the supporting resource.

name A string. Name of the resource supporting the service.

ServiceOrderRef relationship

Service Order reference. Useful to understand the which was the Service order through which the service was
instantiated in the service inventory.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the Service Order.

id A string. Unique identifier of the Service Order.

serviceOrderItemId A string. Unique identifier of the Service Order Item within a service order, not
populated if this is a reference to a service order.

ServiceRef relationship

Service reference, for when Service is used by other entities.

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. reference of the service.

id A string. Id of the service.

ServiceSpecificationRef relationship

Service specification reference: ServiceSpecification(s) required to realize a ProductSpecification.

© TM Forum 2019. All Rights Reserved Page 11 of 34

TMF638 Service Inventory API REST Specification

@referredType A string. The actual type of the target instance when needed for disambiguation.

href A string. Reference of the serviceSpecification.

id A string. Unique identifier of the service specification.

name A string. Name of the requiredServiceSpecification.

targetServiceSchema A target service schema (TargetServiceSchema). A target service schema reference

(TargetServiceSchemaRef). The reference object to the schema and type of target
service which is described by service specification.

version A string. Service specification version.

Json representation sample

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

{
"id": "5351",
"href": "[Link]
"serviceType": "Cloud",
"name": "vCPE serial 1355615",
"description": "Instantiation of vCPE",
"state": "Active",
"category": "CFS",
"isServiceEnabled": true,
"hasStarted": true,
"startMode": "1",
"isStateful": true,
"serviceDate": "2018-01-15T12:26:11.747Z",
"startDate": "2018-01-15T12:26:11.747Z",
"serviceSpecification": {
"id": "1212",
"href": "[Link]
"name": "vCPE",
"version": "1.0.0",
"@referredType": "vCPE"
},
"serviceCharacteristic": [
{
"name": "vCPE_IP",
"valueType": "object",
"value": {
"@type": "IPAddress",
"@schemaLocation": "[Link]
"address": "[Link]"
}
}
],
"serviceRelationship": [
{
"relationshipType": "DependentOn",
"service": {

© TM Forum 2019. All Rights Reserved Page 12 of 34

TMF638 Service Inventory API REST Specification

"href": "[Link]
"id": "5645",
"@referredType": "vOS"
}
}
],
"supportingService": [
{
"href": "[Link]
"id": "5885",
"@referredType": "vJavaVM"
}
],
"supportingResource": [
{
"id": "6161",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/5351",
"name": "GenInfra",
"@referredType": "Infra"
},
{
"id": "7171",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/7171",
"name": "BNG_MUX",
"@referredType": "MUX"
}
],
"relatedParty": [
{
"href": "[Link]
"id": "456",
"name": "John Doe",
"role": "user",
"@referredType": "Individual"
}
],
"serviceOrder": [
{
"href": "[Link]
"id": "42",
"serviceOrderItemId": "1"
}
],
"place": [
{
"href": "[Link]
"id": "2435",
"name": "Customer primary location",
"role": "InstallationAddress"
}
],
"note": [

© TM Forum 2019. All Rights Reserved Page 13 of 34

TMF638 Service Inventory API REST Specification

{
"author": "Jean Pontus",
"date": "2018-01-15T12:26:11.748Z",
"text": "This service was installed automatically, no issues were noted in testing."
}
],
"@type": "vCPE",
"@schemaLocation": "[Link]
"@baseType": "Service"
}

Notification Resource Models

5 notifications are defined for this API

Notifications related to Service:

- ServiceCreateNotification
- ServiceAttributeValueChangeNotification
- ServiceStateChangeNotification
- ServiceBatchNotification
- ServiceDeleteNotification

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

© TM Forum 2019. All Rights Reserved Page 14 of 34

TMF638 Service Inventory API REST Specification

Service Create Notification

Notification ServiceCreateNotification case for resource Service

Json representation sample

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

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

Service Attribute Value Change Notification

Notification ServiceAttributeValueChangeNotification case for resource Service

© TM Forum 2019. All Rights Reserved Page 15 of 34

TMF638 Service Inventory API REST Specification

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 ServiceStateChangeNotification case for resource Service

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 ServiceBatchNotification case for resource Service

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" :
{-- SEE Service RESOURCE SAMPLE --}
}
}

© TM Forum 2019. All Rights Reserved Page 16 of 34

TMF638 Service Inventory API REST Specification

Service Delete Notification

Notification ServiceDeleteNotification case for resource Service

Json representation sample

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

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

© TM Forum 2019. All Rights Reserved Page 17 of 34

TMF638 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 Part 1 document.

Notifications are also described in a subsequent section.

© TM Forum 2019. All Rights Reserved Page 18 of 34

TMF638 Service Inventory API REST Specification

Operations on Service

List services

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

This operation list service 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 multiple services.

Request

GET {apiRoot}/service?fields=id,category,name,state&category=cloud&[Link]=3643
Accept: application/json

Response

200

[
{
"id": "5351",
"name": "vCPE serial 1355615",
"state": "Active",
"category": "CFS"
},
{
"id": "5352",
"name": "vDPI serial 1355445",
"state": "Active",
"category": "CFS"
}
]

Retrieve service

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

© TM Forum 2019. All Rights Reserved Page 19 of 34

TMF638 Service Inventory API REST Specification

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 specific service.

Request

GET {apiRoot}/service/5351
Accept: application/json

Response

200

{
"id": "5351",
"href": "[Link]
"serviceType": "Cloud",
"name": "vCPE serial 1355615",
"description": "Instantiation of vCPE",
"state": "Active",
"category": "CFS",
"isServiceEnabled": true,
"hasStarted": true,
"startMode": "1",
"isStateful": true,
"serviceDate": "2018-01-15T12:26:11.747Z",
"startDate": "2018-01-15T12:26:11.747Z",
"serviceSpecification": {
"id": "1212",
"href": "[Link]
"name": "vCPE",
"version": "1.0.0",
"@referredType": "vCPE"
},
"serviceCharacteristic": [
{
"name": "vCPE_IP",
"valueType": "object",
"value": {
"@type": "IPAddress",
"@schemaLocation": "[Link]
"address": "[Link]"
}

© TM Forum 2019. All Rights Reserved Page 20 of 34

TMF638 Service Inventory API REST Specification

}
],
"serviceRelationship": [
{
"relationshipType": "DependentOn",
"service": {
"href": "[Link]
"id": "5645",
"@referredType": "vOS"
}
}
],
"supportingService": [
{
"href": "[Link]
"id": "5885",
"@referredType": "vJavaVM"
}
],
"supportingResource": [
{
"id": "6161",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/5351",
"name": "GenInfra",
"@referredType": "Infra"
},
{
"id": "7171",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/7171",
"name": "BNG_MUX",
"@referredType": "MUX"
}
],
"relatedParty": [
{
"href": "[Link]/tmf-api/partyManagement/v4/party/456",
"id": "456",
"name": "John Doe",
"role": "user"
}
],
"serviceOrder": [
{
"href": "[Link]
"id": "42",
"serviceOrderItemId": "1"
}
],
"place": [
{
"href": "[Link]

© TM Forum 2019. All Rights Reserved Page 21 of 34

TMF638 Service Inventory API REST Specification

"id": "2435",
"name": "Customer primary location",
"role": "InstallationAddress"
}
],
"note": [
{
"author": "Jean Pontus",
"date": "2018-01-15T12:26:11.748Z",
"text": "This service was installed automatically, no issues were noted in testing."
}
],
"@type": "vCPE",
"@schemaLocation": "[Link]
"@baseType": "Service"
}

Create service

POST /service
Description

This operation creates a service entity.

Mandatory and Non Mandatory Attributes

The following tables provides the list of mandatory and non mandatory attributes when creating a Service,
including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add
additional mandatory attributes.

Mandatory Attributes Rule

state
[Link]

Non Mandatory Attributes Default Value Rule

category
description
endDate blank
hasStarted false
isServiceEnabled
isStateful true
name
note
place
relatedParty
serviceCharacteristic
serviceDate <date of POST>
serviceOrder

© TM Forum 2019. All Rights Reserved Page 22 of 34

TMF638 Service Inventory API REST Specification

Non Mandatory Attributes Default Value Rule

serviceRelationship
serviceSpecification
serviceType
startDate <date of POST>
startMode
supportingResource
supportingService

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 OR href
serviceSpecification id OR href
relatedParty id OR href, role
serviceRelationship id OR href,
relationshipType
supportingService id OR href
supportingResource id OR href
note date, author,
text
place id OR href, role
Characteristic name,
valueType, value

Usage Samples

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

Request

POST {apiRoot}/service
Content-Type: application/json

{
"serviceType": "Cloud",
"name": "vCPE serial 1355615",
"description": "Instantiation of vCPE",
"state": "Reserved",
"category": "CFS",
"isServiceEnabled": false,
"hasStarted": false,
"startMode": "1",

© TM Forum 2019. All Rights Reserved Page 23 of 34

TMF638 Service Inventory API REST Specification

"isStateful": true,
"serviceSpecification": {
"id": "1212",
"href": "[Link]
"name": "vCPE",
"version": "1.0.0",
"@referredType": "vCPE"
},
"serviceCharacteristic": [
{
"name": "vCPE_IP",
"valueType": "object",
"value": {
"@type": "IPAddress",
"@schemaLocation": "[Link]
"address": "[Link]"
}
}
],
"serviceRelationship": [
{
"relationshipType": "DependentOn",
"service": {
"href": "[Link]
"id": "5645",
"@referredType": "vOS"
}
}
],
"relatedParty": [
{
"href": "[Link]/tmf-api/partyManagement/v4/party/456",
"id": "456",
"name": "John Doe",
"role": "user"
}
],
"serviceOrder": [
{
"href": "[Link]
"id": "42",
"serviceOrderItemId": "1"
}
],
"place": [
{
"href": "[Link]
"id": "2435",
"name": "Customer primary location",
"role": "InstallationAddress"
}
],
"@type": "vCPE",
"@schemaLocation": "[Link]
"@baseType": "Service"

© TM Forum 2019. All Rights Reserved Page 24 of 34

TMF638 Service Inventory API REST Specification

Response

201

{
"id": "5351",
"href": "[Link]
"serviceType": "Cloud",
"name": "vCPE serial 1355615",
"description": "Instantiation of vCPE",
"state": "Reserved",
"category": "CFS",
"isServiceEnabled": false,
"hasStarted": false,
"startMode": "1",
"isStateful": true,
"serviceDate": "2018-01-15T12:26:11.747Z",
"serviceSpecification": {
"id": "1212",
"href": "[Link]
"name": "vCPE",
"version": "1.0.0",
"@referredType": "vCPE"
},
"serviceCharacteristic": [
{
"name": "vCPE_IP",
"valueType": "object",
"value": {
"@type": "IPAddress",
"@schemaLocation": "[Link]
"address": "[Link]"
}
}
],
"serviceRelationship": [
{
"relationshipType": "DependentOn",
"service": {
"href": "[Link]
"id": "5645",
"@referredType": "vOS"
}
}
],
"relatedParty": [
{
"href": "[Link]/tmf-api/partyManagement/v4/party/456",
"id": "456",
"name": "John Doe",
"role": "user"

© TM Forum 2019. All Rights Reserved Page 25 of 34

TMF638 Service Inventory API REST Specification

}
],
"serviceOrder": [
{
"href": "[Link]
"id": "42",
"serviceOrderItemId": "1"
}
],
"place": [
{
"href": "[Link]
"id": "2435",
"name": "Customer primary location",
"role": "InstallationAddress"
}
],
"@type": "vCPE",
"@schemaLocation": "[Link]
"@baseType": "Service"
}

Patch service

PATCH /service/{id}
Description

This operation allows partial updates of a service entity. Support of json/merge

([Link] is mandatory, support of json/patch ([Link] 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

category
description
endDate
hasStarted
isServiceEnabled
isStateful
name
note

© TM Forum 2019. All Rights Reserved Page 26 of 34

TMF638 Service Inventory API REST Specification

Patchable Attributes Rule

place
relatedParty
serviceCharacteristic
serviceDate
serviceOrder
serviceSpecification
serviceType
startDate
startMode
state
supportingResource
supportingService

Non Patchable Attributes Rule

id
href
serviceRelationship

Usage Samples

Here's an example of a request for patching a service. In this example, a new version is set, together with validity
period.

Request

PATCH {apiRoot}/service/5351
Content-Type: application/merge-patch+json

{
"supportingService": [
{
"href": "[Link]
"id": "5885",
"@referredType": "vJavaVM"
}
],
"supportingResource": [
{
"id": "6161",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/5351",
"name": "GenInfra",
"@referredType": "Infra"
},
{
"id": "7171",
"href": "[Link]

© TM Forum 2019. All Rights Reserved Page 27 of 34

TMF638 Service Inventory API REST Specification

api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/7171",
"name": "BNG_MUX",
"@referredType": "MUX"
}
]
}

Response

200

{
"id": "5351",
"href": "[Link]
"serviceType": "Cloud",
"name": "vCPE serial 1355615",
"description": "Instantiation of vCPE",
"state": "Active",
"category": "CFS",
"isServiceEnabled": true,
"hasStarted": false,
"startMode": "1",
"isStateful": true,
"serviceDate": "2018-01-15T12:26:11.747Z",
"serviceSpecification": {
"id": "1212",
"href": "[Link]
"name": "vCPE",
"version": "1.0.0",
"@referredType": "vCPE"
},
"serviceCharacteristic": [
{
"name": "vCPE_IP",
"valueType": "object",
"value": {
"@type": "IPAddress",
"@schemaLocation": "[Link]
"address": "[Link]"
}
}
],
"serviceRelationship": [
{
"relationshipType": "DependentOn",
"service": {
"href": "[Link]
"id": "5645",
"@referredType": "vOS"
}
}
],

© TM Forum 2019. All Rights Reserved Page 28 of 34

TMF638 Service Inventory API REST Specification

"supportingService": [
{
"href": "[Link]
"id": "5885",
"@referredType": "vJavaVM"
}
],
"supportingResource": [
{
"id": "6161",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/5351",
"name": "GenInfra",
"@referredType": "Infra"
},
{
"id": "7171",
"href": "[Link]
api/resourceInventoryManagement/v4/resource/[Link]
api/serviceInventoryManagement/v4/service/7171",
"name": "BNG_MUX",
"@referredType": "MUX"
}
],
"relatedParty": [
{
"href": "[Link]/tmf-api/partyManagement/v4/party/456",
"id": "456",
"name": "John Doe",
"role": "user"
}
],
"serviceOrder": [
{
"href": "[Link]
"id": "42",
"serviceOrderItemId": "1"
}
],
"place": [
{
"href": "[Link]
"id": "2435",
"name": "Customer primary location",
"role": "InstallationAddress"
}
],
"note": [
{
"author": "Jean Pontus",
"date": "2018-01-15T12:26:11.748Z",
"text": "This service was installed automatically, no issues were noted in testing."
}
],

© TM Forum 2019. All Rights Reserved Page 29 of 34

TMF638 Service Inventory API REST Specification

"@type": "vCPE",
"@schemaLocation": "[Link]
"@baseType": "Service"
}

Delete service

DELETE /service/{id}
Description

This operation deletes a service entity.

Usage Samples

Here's an example of a request for deleting a service.

Request

DELETE {apiRoot}/service/5351

Response

204

© TM Forum 2019. All Rights Reserved Page 30 of 34

TMF638 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 Part 1. Refer to the guidelines for more details.

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": "[Link]

Response

201
Content-Type: application/json
Location: /api/hub/42

{"id":"42","callback":"[Link]

© TM Forum 2019. All Rights Reserved Page 31 of 34

TMF638 Service Inventory API REST Specification

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

© TM Forum 2019. All Rights Reserved Page 32 of 34

TMF638 Service Inventory API REST Specification

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 Part 1 document.

© TM Forum 2019. All Rights Reserved Page 33 of 34

TMF638 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 data model
TM Forum
Version 1.0.0 pgauthier@[Link]

Nicoleta Stoica
Vodafone
[Link]@[Link]

Mariano Belaunde
Orange Labs

Release 18.0 31-Jan-2018 Pierre Gauthier Alignment with TMF open API
TM Forum guidelines 3.0
Version 2.0.0 pgauthier@[Link]
Review with SID Team (Cécile
Ludovic Robert Orange Ludwichowski)
[Link]@[Link]

Release 18.5 13-Jan-2018 Jonathan Goldberg Schema alignment for NaaS APIs in
release 18.5
Version 4.0.0 Amdocs

[Link]@[Link]

Contributors to Document

Pierre Gauthier TM Forum

Nicoleta Stoica Vodafone (formerly)

Mariano Belaunde Orange

Ludovic Robert Orange

Jonathan Goldberg Amdocs

© TM Forum 2019. All Rights Reserved Page 34 of 34