Hackathon Quick Presentation
Introductory Presentation
See detailed description of TM Forum APIs on the Developer Portal
Download API Specifications GitHub
Get all the TM Forum Specifications with examples from GitHub.
Download POSTMAN Collections GitHub
Download the POSTMAN Colletions and test all the TM Forum APIs running on our Sandbox
Download the Swaggers and test all the TM Forum APIs running on our Sandbox
Read the TM Forum APIS for Dummies
Familiarize yourself with the TM Forum APIs by reading this simple guide.
TM Forum APIs Ecosystem Architecture
Read about the TM Forum API Ecosystem
Get POSTMAN form Google.
TM Forum APIs
The following APIs are provided:
-Trouble Ticket API
-Product Ordering API
-Product Catalog API
-Usage Management API
-Product Inventory API
-Billing Management API
-Performance Management API
-SLA Management API
-Customer Management API
-Party Management API
...
Managed Entity and Task Resource Models
Example of the JSON representation of a ticket:
{ |
GET /API/troubleTicket/{ID}}/?{fields=attributes}&{filtering expression}
This Uniform Contract operation is used to retrieve the representation of a ticket.
Note that collections can be retrieved via GET /API/troubleTicket/ with no {ID}
Filtering is allowed on all attributes. See example below.
Attribute selection is possible for all attributes. See example below.
| REQUEST |
GET /api/troubleTicket Accept: application/json |
| RESPONSE |
200 Content-Type: application/json
[ { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "In Progress", "subStatus": "Held", "statusChangeReason": "Waiting for invoicing expert.", "statusChangeDate": "2013-07-24T08:55:12.0Z", "relatedParty": [ { "href": "/customer/1234", "role": "Originator" }, { "href": "/operator/1234", "role": "Owner" }, { "href": "Roger Collins", "role": "Reviser" } ], "relatedObject": [ { "involvement": "Disputed", "reference": "/invoice/1234" }, { "involvement": "Adjusted", "reference": "/invoice/5678" } ], "note": [ { "date": "2013-07-24T09:55:30.0Z", "author": "Arthur Evans", "text": "Already called the expert" }, { "date": "2013-07-25T08:55:12.0Z", "author": "Arthur Evans", "text": "Informed the originator" } ] }, { "id": "2", "correlationId": "", "description": "Customer asks for information about upgrading products.", "severity": "Low", "type": "Products and Services", "creationDate": "2013-07-25T08:16:00.0Z", "targetResolutionDate": "2013-07-28T00:00:00.0Z", "status": "", "subStatus": "", "statusChangeReason": "", "statusChangeDate": "2013-07-25T08:16:00.0Z", "resolutionDate": "", "relatedParty": [ { "href": "/customer/4567", "role": "Originator" } ], "relatedObject": [ ], "note": [ ] } ] |
POST API/ticket
Description :
- This Uniform Contract operation is used to create a ticket.
- Resource represents a managed entity.
- Mandatory attributes that must be provided when you create the ticket :
Description, severity, type
Behavior :
- Returns HTTP/1.1 status code 201 if the request was successful.
- Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).
Attribute name | Mandatory | Default | Rule |
|---|---|---|---|
Id | N |
| Initialized by TT handler |
correlationId | N |
|
|
description | Y |
|
|
severity | Y |
|
|
type | Y |
|
|
creationDate | N | Date of the day | Initialized by TT handler |
targetResolutionDate | N |
|
|
status | N | Created | Initialized by TT handler |
subStatus | N |
|
|
statusChangeReason | N |
|
|
statusChangeDate | N | Date of the day |
|
resolutionDate | N |
|
|
relatedParty | N |
|
|
relatedObject | N |
|
|
Note | N |
|
|
The requester should not provide an id – it is generated automatically by the TT handler. A correlationId can be provided, but is not mandatory.
Create a ticket only with mandatory attributes:
REQUEST |
POST API/ troubleTicket Content-type: application/json
{ "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment" } |
| RESPONSE |
201 Content-Type: application/json { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "Created", "subStatus": "", "statusChangeReason": "", "statusChangeDate": "2013-07-24T08:55:12.0Z", "resolutionDate": "", "relatedParty": [ ], "relatedObject": [ ], "note": [ ] |
API NOTIFICATION FOR TICKET
It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.
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 :
...
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} |
...
Managed Entity and Task Resource Models
Example of the JSON representation of a product order:
| { "id": "42", "href": "http://serverlocation:port/orderManagement/productOrder/42", "externalId": "NiceNameForTheConsumer_42", "priority": "1", "description": "A wonderful 42 order for brand new products", "category": "residential", "state": "InProgress", "orderDate": "2013-04-12T16:42:23-04:00", "completionDate": "2013-04-19T16:42:23-04:00", "requestedStartDate": "2013-04-12T16:42:23-04:00", "requestedCompletionDate": "2013-04-19T16:42:23-04:00", "expectedCompletionDate": "2013-04-19T16:42:23-04:00", "notificationContact": "[email protected]", "note": [ { "text": "A free text detailing the note", "date": "2013-04-12T16:42:23-04:00", "author": "name" } ], "relatedParty": [ { "role": "customer", "id": "345221", "href": "http://serverlocation:port/partyManagement/customer/345221", "name": "John Doe" }, { "role": "partner", "id": "42", "href": "http://serverlocation:port/partyManagement/partner/42" }, { "role": "seller", "id": "4563", "href": "http://serverlocation:port/partnerManagement/partner/4563" } ], "orderItem": [ { "id": "1", "action": "add", "state": "Acknowledged", "billingAccount": [ { "id": "123456", "href": "http://serverlocation:port/billingManagement/billingAccount/123456" } ], "appointment": "http://www.doodle.com/1WCV5647438", "productOffering": { "id": "42", "href": "http: //serverlocation: port/catalogManagement/productOffering/42" }, "product": { "place": { "href": "http://map.google.com/.../1234112GDE", "role": "DeliveryPlace" }, "productCharacteristic": [ { "name": "Colour", "value": "White" }, { "name": "Memory", "value": "16" } ] } }, { "id": "2", "action": "modify", "state": "InProgress", "productOffering": { "id": "43", "href": "http: //serverlocation: port/catalogManagement/productOffering/43" }, "product": { "id": "456", "href": "http: //serverlocation: port/inventoryManagement/product/456", "productCharacteristic": [ { "name": "anotherCharacteristic", "value": "itsValue" } ], "relatedParty": [ { "role": "user", "id": "5667443", "href": "http://serverlocation:port/partyManagement/user/5667443", "name": "Jimmy Doe" } ] } }, { "id": "3", "action": "add", "state": "InProgress", "billingAccount": [ { "id": "123456", "href": "http://serverlocation:port/billingManagement/billingAccount/123456" } ], "productOffering": { "id": "51", "href": "http: //serverlocation: port/catalogManagement/productOffering/51" }, "product": { "id": "511", "href": "http: //serverlocation: port/inventoryManagement/product/456", "productCharacteristic": [ { "name": "anotherCharacteristic", "value": "itsValue" } ], "productRelationship": [ { "type": "reliesOn", "product": { "productCharacteristic": [ { "name": "MSISDN", "value": "003467488299002" } ] } } ] } }, { "id": "4", "action": "add", "state": "InProgress", "billingAccount": [ { "id": "1789", "href": "http://serverlocation:port/billingManagement/billingAccount/1789" } ], "productOffering": { "id": "44", "href": "http://serverlocation:port/catalogManagement/productOffering/Bundle44", "bundledProductOffering": [ { "id": " BundledPSTN444", "href": "http://serverlocation:port/catalogManagement/productOffering/BundledPSTN444" }, { "id": " Bundled Mobile443", "href": "http://serverlocation:port/catalogManagement/productOffering/BundledMobile443" } ] }, "product": { "productRelationship": [ { "type": "bundled", "product": { "productCharacteristic": [ { "name": "PSTNNumber", "value": "003427488299002" } ] } }, { "type": "bundled", "product": { "productCharacteristic": [ { "name": "MobileNumber", "value": "003464553000300" } ] } } ] } } ] } |
GET /orderManagement/productOrder/{ID}
Note that collections can be retrieved via GET /orderManagement/productOrder with no {ID}
Description :
This operation is used to retrieve order information using the ID
Attribute selection is enabled on all first level attributes but not on inner classes.
Attribute selection may optionally be enabled on all attributes and inner classes.
Behavior :
· Return status codes
o 200 OK - the request was successful
o 404 Not found - the supplied ID does not match a known productOrder
Use case : Get a specific order based on its ID
REQUEST |
GET /orderManagement/productOrder/42 Accept: application/json |
RESPONSE |
200 Content-Type: application/json { "appointment":"http://www.doodle.com/1WCV5647438", { |
POST orderManagement/productorder
Description:
This operation is used to create a new order.
The mandatory attributes for the creation are :
- relatedParties.role and reference to identify at least the customer
- at least one orderItem with :
- an action
- a productOffering
Behavior :
- Return status codes
- 201 Created - the request was successful
- 400 Bad Request – error
- Return status codes
REQUEST |
POST /orderManagement/productOrder Content-type: application/json
{ "note":[ |
RESPONSE |
201 Content-Type: application/json { |
...
Managed Entity and Task Resource Models
Example of the JSON representation of a product offering:
{ "id": "42", "href": "http://serverlocation:port/productCatalogManagement/productOffering/42", "version": "2.0", "lastUpdate": "2013-04-19T16:42:23.0Z", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": true, "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23.0Z", "endDateTime": "2013-06-19T00:00:00.0Z" }, "category": [ { "id": "12", "href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ { "id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" } ], "place": [ { "id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" } ], "bundledProductOffering": [ { "id": "15", "href": "http://serverlocation:port/productCatalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, { "id": "64", "href": "http://serverlocation:port/productCatalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": { "id": "28", "href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": { "id": "13", "href": "http://serverlocation:port/productCatalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" }, "serviceCandidate": { "id": "13", "href": "http://serverlocation:port/serviceCatalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" }, "resourceCandidate": { "id": "13", "href": "http://serverlocation:port/resourceCatalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" }, "productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23.0Z", "endDateTime": "2013-06-19T00:00:00.0Z" } } ], "productOfferingPrice": [ { "name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23.0Z", "endDateTime": "2013-06-19T00:00:00.0Z" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": 12, "dutyFreeAmount": 10, "taxRate": 20, "currencyCode": "EUR", "percentage": 0 },
"recurringChargePeriod": "monthly" }, { "name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23.0Z", "endDateTime": "2013-06-19T00:00:00.0Z" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": 12, "dutyFreeAmount": 10, "taxRate": 20, "currencyCode": "EUR", "percentage": 0 }, "recurringChargePeriod": "", "productOfferPriceAlteration": { "name": "Shipping Discount", "description": "One time shipping discount", "validFor": { "startDateTime": "2013-04-19T16:42:23.0Z" }, "priceType": "One Time discount", "unitOfMeasure": "", "price": { "percentage": 100 }, "recurringChargePeriod": "", "priceCondition": "apply if total amount of the order is greater than 300.00" } } ] } |
GET /catalogManagement/productOffering/{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 :
- This operation returns all productOfferings from the catalog, unless an ID is specified in which case a specific productOffering resource would be returned. The ProductOffering resource represents entities that are orderable from the provider of the catalog. This resource includes pricing information.
- The resource instance being returned is a productOffering or an array of product offering if the query returns multiple resources
- The resource is either a managed entity or a collection depending on the query pattern.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 200 if no productOffering found for supplied categoryId (200) (filter expression)
- 404 Not found when the supplied ID doesn’t match a known productOffering.
- Filtering is enabled on all productOffering attributes.
- What status and exception codes are returned.
Attribute selection is enabled.
...
REQUEST
...
GET /catalogManagement/productOffering/{42}
Accept: application/json
...
RESPONSE
200
Content-Type: application/json
{
"id": "42",
"href": "http://serverlocation:port/catalogManagement/productOffering/42",
"version": "2.0",
"lastUpdate": "2013-04-19T16:42:23-04:00",
"name": "Virtual Storage Medium",
"description": "Virtual Storage Medium",
"isBundle": "true",
"lifecycleStatus": "Active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"category": [
{
"id": "12",
...
"id": "28",
"href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28",
"name": "Standard SLA"
},
"productSpecification": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/productSpecification/13",
"version": "2.0",
"name": "specification product 1"
},
"serviceCandidate":
{
"id": "13",
"href": "http://serverlocation:port/catalogManagement/serviceCandidate/13",
"version": "2.0",
"name": "specification service 1"
},
"resourceCandidate": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/resourceCandidate/13",
"version": "2.0",
"name": "specification resource 1"
},
"productOfferingTerm": [
{
"name": "12 Month",
"description": "12 month contract",
"duration": "12",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
}
}
],
"productOfferingPrice": [
{
"name": "Monthly Price",
"description": "monthlyprice",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"priceType": "recurring",
"unitOfMeasure": "",
"price": {
"taxIncludedAmount": "12.00",
"dutyFreeAmount": "10.00",
"taxRate": "20.00",
"currencyCode": "EUR"
},
"recurringChargePeriod": "monthly"
}, {
"name": "Usage Price",
"description": "usageprice",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"priceType": "usage",
"unitOfMeasure": "second",
"price": {
"taxIncludedAmount": "12.00",
"dutyFreeAmount": "10.00",
"taxRate": "20.00",
"currencyCode": "EUR"
},
"recurringChargePeriod": ""
}
]
}
POST /catalogManagement/productOffering
This Uniform Contract operation is used to create a managed entity or a task.
Description :
· This operation creates a productOffering
· The resource represents a managed entity.
· The ID may be a string (or a string containing numbers).
Behavior :
- · Standard POST behavior.
- Returns HTTP/1.1 status code 201 if the request was successful.
- Any other special return and/or exception codes.
...
REQUEST
...
POST catalogManagement/productOffering
Content-type: application/json
{
"version": "1.0",
"name": "Virtual Storage Medium",
"description": "Virtual Storage Medium",
"isBundle": "true",
"lifecycleStatus": "Active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"category": [
{
"id": "12",
"href": "http://serverlocation:port/catalogManagement/category/12",
"version": "2.0",
"name": "Cloud offerings"
}
],
"channel": [
{
"id": "13",
"href": "http://serverlocation:port/marketSales/channel/13",
"name": "Online Channel"
}
],
"place": [
{
"id": "12",
"href": "http://serverlocation:port/marketSales/place/12",
"name": "France"
}
],
"bundledProductOffering": [
{
"id": "15",
"href": "http://serverlocation:port/catalogManagement/productOffering/15",
"lifecycleStatus": "Active",
"name": "Offering 15"
}, {
"id": "64",
"href": "http://serverlocation:port/catalogManagement/productOffering/64",
"lifecycleStatus": "Active",
"name": "Offering 64"
}
],
"serviceLevelAgreement": {
"id": "28",
"href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28",
"name": "Standard SLA"
},
"productSpecification": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/productSpecification/13",
"version": "2.0",
"name": "specification product 1"
},
"serviceCandidate": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/serviceCandidate/13",
"version": "2.0",
"name": "specification service 1"
},
"resourceCandidate": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/resourceCandidate/13",
"version": "2.0",
"name": "specification resource 1"
},
"productOfferingTerm": [
{
"name": "12 Month",
"description": "12 month contract",
"duration": "12",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
}
}
],
"productOfferingPrice": [
{
"name": "Monthly Price",
"description": "monthlyprice",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"priceType": "recurring",
"unitOfMeasure": "",
"price": {
"taxIncludedAmount": "12.00",
"dutyFreeAmount": "10.00",
"taxRate": "20.00",
"currencyCode": "EUR"
},
"recurringChargePeriod": "monthly"
}, {
"name": "Usage Price",
"description": "usageprice",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"priceType": "usage",
"unitOfMeasure": "second",
"price": {
"taxIncludedAmount": "12.00",
"dutyFreeAmount": "10.00",
"taxRate": "20.00",
"currencyCode": "EUR"
},
"recurringChargePeriod": ""
}
]
}
...
RESPONSE
201
Content-Type: application/json
{
"id": "42",
"href": "http://serverlocation:port/catalogManagement/productOffering/42",
"version": "1.0",
"lastUpdate": "2013-04-19T16:42:23-04:00",
"name": "Virtual Storage Medium",
"description": "Virtual Storage Medium",
"isBundle": "true",
"lifecycleStatus": "Active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"category": [
{
"id": "12",
"href": "http://serverlocation:port/catalogManagement/category/12",
"version": "2.0",
"name": "Cloud offerings"
}
],
"channel": [
{
"id": "13",
"href": "http://serverlocation:port/marketSales/channel/13",
"name": "Online Channel"
}
],
"place": [
{
"id": "12",
"href": "http://serverlocation:port/marketSales/place/12",
"name": "France"
}
],
"bundledProductOffering": [
{
"id": "15",
"href": "http://serverlocation:port/catalogManagement/productOffering/15",
"lifecycleStatus": "Active",
"name": "Offering 15"
}, {
"id": "64",
"href": "http://serverlocation:port/catalogManagement/productOffering/64",
"lifecycleStatus": "Active",
"name": "Offering 64"
}
],
"serviceLevelAgreement": {
"id": "28",
"href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28",
"name": "Standard SLA"
},
"productSpecification": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/productSpecification/13",
"version": "2.0",
"name": "specification product 1"
},
"serviceCandidate": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/serviceCandidate/13",
"version": "2.0",
"name": "specification service 1"
},
"resourceCandidate": {
"id": "13",
"href": "http://serverlocation:port/catalogManagement/resourceCandidate/13",
"version": "2.0",
"name": "specification resource 1"
},
"productOfferingTerm": [
{
"name": "12 Month",
"description": "12 month contract",
"duration": "12",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
}
}
],
"productOfferingPrice": [
{
"name": "Monthly Price",
"description": "monthlyprice",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"priceType": "recurring",
"unitOfMeasure": "",
"price": {
"taxIncludedAmount": "12.00",
"dutyFreeAmount": "10.00",
"taxRate": "20.00",
"currencyCode": "EUR"
},
"recurringChargePeriod": "monthly"
}, {
...