<name of API>

API REST Specification

Document Number<e.g. TMF633>
August 2017

Release: <e.g. Frameworx Release 17.0> Document Status:<e.g. Draft>

Version: <e.g. 2.0.0> IPR Mode: <e.g. RAND>

TM Forum 2013. All Rights Reserved.

NOTICE
Copyright © TM Forum 2017. All Rights Reserved.

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

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

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

Direct inquiries to the TM Forum office:

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

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

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

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

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

Introduction ...................................................................................................................................................... 5

RESOURCE MODEL ....................................................................................................................................... 7

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

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

API OPERATION TEMPLATES .................................................................................................................... 13

GET /api/<RESOURCE>/{ID} ..........................................................................................................................................................

PUT API/{RESOURCE}/{ID} ............................................................................................................................................................

PATCH API/{RESOURCE}/{ID} .......................................................................................................................................................

POST API/{RESOURCE}/{ID} .........................................................................................................................................................

DELETE API/{RESOURCE}/{ID} .....................................................................................................................................................

API NOTIFICATIOn TEMPLATES ................................................................................................................. 23

REGISTER LISTENER POST /hub .................................................................................................................................................

UNREGISTER LISTENER DELETE hub/{id} ..................................................................................................................................

publish {EventTYPE} POST /listener ...............................................................................................................................................

Release History ................................................................................................................................................................................

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

LIST OF TABLES

Table 1: SMI Operations Error! Bookmark not defined.

Table 2: SMI Diagram View Error! Bookmark not defined.
Table 3: Terms related to service framework context Error! Bookmark not defined.
Table 4: Terms related to the global context Error! Bookmark not defined.

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

INTRODUCTION
The following document is the template for the REST API documentation. Please provide a description of the API
here.

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

SAMPLE USE CASES
Please provide some sample use cases here. Description of how the API is used in context.

Sample Use Case

Provide Sample Example from Profile Template. From the Profile when we have it.

Description of Use Case

Example of API Usage in the Context of the Use Case

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

RESOURCE MODEL

Managed Entity and Task Resource Models

For every single resource managed by the API provide a JSON based representation of the
managed entities and tasks.

Also remember that you representation must be based on the SID at least from a conceptual
view point.

Also define the structure of the Resource IDs.

For example the SMAPI 2.0 use the following Management Report representation:

“id”: « 42 »,

"datetime": "2012-12-20 15:00:00",

"health_state": "operational",

"metrics": [

"code": "123",

"category_id": "45",

"date_time": "2012-12-20 14:30:00",

"reference": "4321",

"source_id": "8f27ce50-4b00-11e2-bcfd-0800200c9a66",

"value": 50,

"metric_id": "b0dbbc50-4b00-11e2-bcfd-0800200c9a66"

},

"code": "321",

"category_id": "48",

"date_time": "2012-12-20 14:30:00",

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

 "reference": "4321",

"source_id": "8f27ce50-4b00-11e2-bcfd-0800200c9a66",

"value": 50,

"metric_id": "c50f3e90-4b00-11e2-bcfd-0800200c9a66"

],

"failures": [

"failure_id": "0bec4420-4b01-11e2-bcfd-0800200c9a66",

"detail": "Network authentication failure",

"source_id": "24b2bc00-4b01-11e2-bcfd-0800200c9a66"

},

"failure_id": "3b687c50-4b01-11e2-bcfd-0800200c9a66",

"detail": "Network authentication failure",

"source_id": "462f1f40-4b01-11e2-bcfd-0800200c9a66"

},

For each resource in your model fill the following table.

Field Description

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

For each resource in your API provide a UML model:

CustomerAccountRelationship

«SystemEnt» «SystemEnt»
PaymentMeans Balance
CustomerAccount
«SystemAtt» «SystemAtt»
- id :String - id :String + creditLimit
- name :String - name :String + pin :String
«Rose_Property»
+ ID :String
CustomerBillSpecBalance + name :String
CustomerBillSpecPaymentMeans
«SystemAss» 1 + accountType :String
«SystemAss» + accountStatus :String
{bag}
«SystemEnt»
relatedParty BillSpecifiedBy
CustomerBillSpec *
{bag}
«SystemAtt»
CustomerBillSpecRelatedParty + name :String
- role :String
+ validFor :TimePeriod CustomerBillSpecCurrency «SystemEnt»
- partyRole :String «SystemAss»
«SystemAtt» «SystemAss» Currency
- id :String
- ratingType :String «SystemAtt»
* - state :String - currencyCode :String
{bag}
CustomerBillSpecMediaBasedUpon
CycleSpecSchedulesCreationOfBillDescribedBy «SystemAss»
1
{bag}
* CustomerBillSpecAppearanceBasedUpon
{bag} *
CustomerBillPresentationMedia
{bag}
CustomerBillingCycleSpecification CustBillFormatAppearsBasedUpon + name :String
«SystemAtt»
+ name :String CustomerBillFormat - id :String
+ billingDateShift :Integer * 1..*
+ name :String
«SystemAtt» + description :String {bag} {bag}
- id :String
- frequency :String

Figure 1 – CustomerBillSpec resource model

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

Event Models

For every single event supported by the API provide a JSON based representation of the
managed event.

You can start with an XML representation but remember that the default representation will be
JSON.

Remember that the Pub/Sub models are common and described in the TMF REST Design
Guidelines.

For example the SMAPI 2.0 use the following Management Report Event representation:

{
"event": {
"dateTime": null,
"id": "42",
"state": {
"healthState": "UNKNOWN",
"executionState": "ACTIVE"
},
"metrics": [
{
"code": "76e27e2b-644e-11e2-8ea1-5c260a86d1e4",
"categoryID": null,
"dateTime": 1367266835571,
"reference": null,
"sourceID": null,
"value": "20",
"metricID": null
},

{
"code": "7987c7bc-644e-11e2-8ea1-5c260a86d1e4",
"categoryID": null,
"dateTime": 1367266835573,
"reference": null,
"sourceID": null,
"value": "60000",
"metricID": null
},
{

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

 "code": "7c7d6e22-644e-11e2-8ea1-5c260a86d1e4",
"categoryID": null,
"dateTime": 1367266835573,
"reference": null,
"sourceID": null,
"value": "12",
"metricID": null
},
{
"code": "7c98ea37-644e-11e2-8ea1-5c260a86d1e4",
"categoryID": null,
"dateTime": 1367266835573,
"reference": null,
"sourceID": null,
"value": "70000",
"metricID": null
},
{
"code": "7dd589b2-644e-11e2-8ea1-5c260a86d1e4",
"categoryID": null,
"dateTime": 1367266835573,
"reference": null,
"sourceID": null,
"value": "89",
"metricID": null
}
]

},
"eventType": "ManagementReport"
}

For each Event in your API fill the following table:

Field Description

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

<Document #, Version #> © TM Forum 2013. All Rights Reserved. Page 12
API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample
REST requests and responses.

Remember that the following Uniform Contract rules must be used :

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.

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

GET /api/<RESOURCE>/{ID}

This Uniform Contract operation is used to retrieve the representation of a managed entity or a
task.

Note that collections can be retrieved via GET /API/<RESOURCE> with no {ID}

Description :

 Provide an overall description of the Operation

 Describe the returned representation of the <resource> instance(s).
 Describe if filtering is enabled and what can be done using query parameters.
 Describe if attribute selection is enabled.
 Describe if the resource represents a managed entity, a collection or a task.
 Describe the structure of the identifier.

Behavior :

 What status and exception codes are returned.

 Returns HTTP/1.1 status code 200 if the request was successful.
 Any other special return and/or exception codes.
 Specify what level of attribute filtering can be used. In fact we mandate L0 (equality)
filtering in every specification as per REST Guidelines. Add this to Template.

REQUEST

GET /api/{Resource}/{ID}/{attributeSelector}?{filtering expression}

Accept: application/json

RESPONSE

200
Content-Type: application/json

{
JSON Resource Representation
}

Example see TMF REST Design Guidelines.

PUT API/{RESOURCE}/{ID}

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

This Uniform Contract operation is used to completely update the representation of a managed
entity or a task.

Description :

 Provide an overall description of the Operation

 Describe the input representation of the <resource> instance.
 Describe if the resource represents a managed entity or a task.
 Describe the structure of the identifier.

Behavior :

 What status and exception codes are returned.

 Returns HTTP/1.1 status code 201 if the request was successful.
 Any other special return and/or exception codes.

REQUEST

PUT API/{RESOURCE}/{ID}
Content-type: application/json

{
JSON Resource Representation with every attributes
}

RESPONSE

201
Content-Type: application/json

{ JSON Resource Representation with every attributes

}

Example see TMF REST Design Guidelines.

PATCH API/{RESOURCE}/{ID}

This Uniform Contract operation is used to partially update the representation of a managed
entity or a task.

Description :

 Provide an overall description of the Operation

 Describe the input representation of the <resource> instance.
 Describe if the resource represents a managed entity or a task.
 Describe the structure of the identifier.

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

Behavior :

 What status and exception codes are returned.

 Returns HTTP/1.1 status code 201 if the request was successful.
 Any other special return and/or exception codes.

Specify which attributes are patchable using the following table (to capture RO attributes)

Attribute name Patchable Rule

ratingType No

Name Y

Valid for. startDateTime Y

Valid for:endDateTime Y After the start date and a

reference to the rule name
in the table below if
complex rule.

CustomerAccount.id Y Should exist

CustomerBillingCycleSpecification.id Y

CustomerBillFormat Y

CustomerBillPresentationMedia Y

Currency code Y

PaymentMeans Y

PartyRole Y Bill receiver is mandatory

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

 state Y Transition state should be
valid

Further document any rules that must be implemented when patching attributes.

Rule name Rule/Pre Condition/Side Effects/Post Conditons

ratedProductUsage Patching When status is patched from below rated to rated

Mandatory Values or billed, the following attributes are mandatory:
"ratingDate", "taxIncludedRatingAmount",
"taxExcludedRatingAmount, "taxRate", "currencyCode ",
"productRef",

ratedProductUsage Patching Default When status is patched resulting in a status of

Values rated or billed, and the following attributes are
empty in the prior state, the following default
values apply:
"usageRatingTag": "Usage",

"isBilled": "False",

"ratingAmountType": "Total",

"isTaxExempt": "false",

"offerTariffType": "Normal"

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

REQUEST

PATCH API/{RESOURCE}/{ID}
Content-type: application/json

{
JSON Resource Representation with every attributes
}

RESPONSE

201
Content-Type: application/json

{ JSON Resource Representation with every attributes

}

Example see TMF REST Design Guidelines.

POST API/{RESOURCE}/{ID}

This Uniform Contract operation is used to create a managed entity or a task.

Description :

 Provide an overall description of the Operation

 Describe the input representation of the <resource> instance.
 Describe if the resource represents a managed entity or a task.
 Describe the structure of the identifier.
 Describe what are the mandatory attributes that must be provided when you create the
entity.

Behavior :

 What status and exception codes are returned.

 Returns HTTP/1.1 status code 201 if the request was successful.
 Any other special return and/or exception codes.

ID Management :

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

 Specify the ID Management Rule POST without specifying the ID must result in the
system generating the ID for the <Entity>. In a specific case, the ID can also be included in
the POST (optional)

Specify the attributes required when an entity is created (and their default values if not):

Attribute name Mandatory Default Rule

ratingType N Postpaid

Name N Customer
name

Valid for. startDateTime N Today Valid date

not earlier
than one bill
cycle in the
past

Valid for:endDateTime N After the

start date

CustomerAccount.id Y Should exist

CustomerBillingCycleSpecification.id N Bill issuer

choice

CustomerBillFormat N Standard
invoice

CustomerBillPresentationMedia N Electronic
invoice

Currency code N National

currency

PaymentMeans N Customer
choice

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

 PartyRole Y Bill receiver
is mandatory

 Further specify any rules on the creation of the entity

Rule name Rule

POST Conditional Mandatory When a usage record is created with a status of rated
Values or billed, the following attributes are mandatory:
"ratingDate", "taxIncludedRatingAmount",
"taxExcludedRatingAmount, "taxRate", "currencyCode ",
"productRef",

POST Mandatory attributes within

object
o Within “disabilities”
 the disability
o Within “characteristics”
 name & value
o Within “organizationIdentification”
 type
 identificationId
o Within “externalReference”
 referenceType
 reference
o Within “relatedParty”
 Role
 Party
 startDateTime
o Within “xxxRelationship”
 relationshipType
 id
 startDateTime

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

REQUEST

POST API/{RESOURCE}
Content-type: application/json

{
JSON Resource Representation with every mandatory attributes
}

RESPONSE

201
Content-Type: application/json

{ JSON Resource Representation with every provided and default attributes

}

Example see TMF REST Design Guidelines.

DELETE API/{RESOURCE}/{ID}

This Uniform Contract operation is used to delete a managed entity or a task.

Description :

 Provide an overall description of the Operation

 Describe if the resource represents a managed entity or a task.
 Describe the structure of the identifier.

Behavior :

 What status and exception codes are returned.

 Returns HTTP/1.1 status code 200 if the request was successful.
 Any other special return and/or exception codes.

REQUEST

DELETE API/{RESOURCE}/{ID}

RESPONSE

200

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

Example see TMF REST Design Guidelines.

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

API NOTIFICATION TEMPLATES

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.

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}

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

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.

REQUEST

DELETE /api/hub/{id}
Accept: application/json

RESPONSE

204

PUBLISH {EVENTTYPE} POST /LISTENER

Description :

Provide the Event description

Behavior :

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

REQUEST

POST /client/listener
Accept: application/json

"event": {

EVENT BODY
},
"eventType": "eventType"
}

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

RESPONSE

201
Content-Type: application/json

Example see TMF REST Design Guidelines.

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

RELEASE HISTORY

Release Date Release led by: Description

Number

Release 1.0 04/15/2013 Pierre Gauthier First Release of Draft Version of the
Document.
TM Forum

pgauthier@tmforum.org

Release 1.1 Updated for use in the Paris Spec

Jam – and rebranded,.

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