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 Entity | PUT Resource | PUT must be used to 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 Entity | POST on TASK Resource | POST must be used to 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. GET /usageManagement/usage/{ID}
The resource is used to retrieve the usage entities.
Filtering is allowed on all attributes.
Attribute selection is possible for all attributes.
GET /usageManagement/usage/{ID}/{attributeSelector}?{filtering expression}
Example REQUEST | GET /usageManagement/usage/1234/fields=date,usageType,usageDescription
Accept: application/json | Example RESPONSE | 200 Content-Type: application/json {
"id": "1234",
"href": " http://serverlocation:port/usageManagement/usage/1234", "date": "2013-05-31T09:00:00+00:01",
"type": "VOICE",
"description": "Description for individual usage content"
} |
All standard error codes apply.
GET /usageManagement/usageSpecification/{ID}The resource is used to retrieve the usage specification entities.
Filtering is allowed on all attributes.
Attribute selection is possible for all attributes. GET usageManagement/usageSpecification/{ID}?{attributeSelector}&{attributeFilter} Example REQUEST | GET usageManagement/usageSpecification/22
Accept: application/json | Example RESPONSE | 200 Content-Type: application/json {
"id": "234",
"href": " http://serverlocation:port/usageManagement/usageSpecification/234",
"name": "CloudCpuSpec",
"description": "Spec for cloud CPU usage",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2099-06-19T00:00:00-04:00"
},
"usageSpecCharacteristic": [
{
"name": "poolNumber",
"description": "the number of the pool",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "",
"valueFrom": "0",
"valueTo": ""
}
]
}, {
"name": "characteristicType",
"description": "sub-type of the characteristic",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "string",
"default": "false",
"value": "Reserved",
"valueFrom": "",
"valueTo": ""
}, {
"valueType": "string",
"default": "false",
"value": "Reserved Gold",
"valueFrom": "",
"valueTo": ""
}, {
"valueType": "string",
"default": "false",
"value": "Reserved Silver",
"valueFrom": "",
"valueTo": ""
}, {
"valueType": "string",
"default": "false",
"value": "Reserved Bronze",
"valueFrom": "",
"valueTo": ""
}, {
"valueType": "string",
"default": "false",
"value": "Burst",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "value",
"description": "value of the usage specified by the unit",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "",
"valueFrom": "0",
"valueTo": ""
}
]
}, {
"name": "unit",
"description": "unit of measure",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "string",
"default": "false",
"value": "GHz",
"valueFrom": "",
"valueTo": ""
}, {
"valueType": "string",
"default": "false",
"value": "Number of vCPU",
"valueFrom": "",
"valueTo": ""
}
]
}
]
} |
Example REQUEST B | GET usageManagement/usageSpecification/?name="cloudCpuSpec"
Accept: application/json | Example RESPONSE B | 200
Content-Type: application/json
(same as above) |
All standard error codes apply.
POST /usagemanagement/usageThe resource is used to create usage entities.
POST without specifying the ID of the usage record must result in the system generating the ID for the usage record (typical). In a specific case, the ID can also be included in the POST (optional)
Attribute selection is possible for all attributes.
POST /usageManagement/usage/{ID}/{attributeSelector} Attribute name | Mandatory | Default | Rule | id | N | Automatically generated | If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used | href | N | Automatically generated | If not given, the href is generated by the system. It is also possible to add an href in the POST request, which is then used | date | Y | | | type | Y | | | description | N | | | usageSpecification | N | | | usageCharacteristic | N | | | status | N | "received" | | relatedParty | N | | | ratedProductUsage | N | | |
Rules:
Rule name | Rule/Pre Condition/Side Effects/Post Conditions | usageCharacteristic | name and value are mandatory | relatedParty | role and party are mandatory startDateTime is not mandatory but has a default value -> it is set to sysdate by default | ratedProductUsage | When a usage record is created with a status of rated or billed, the following attributes are mandatory:
"ratingDate", "taxIncludedRatingAmount", "taxExcludedRatingAmount, "taxRate", "currencyCode ", "productRef" | ratedProductUsage | When a usage record is created with a status of rated or billed, the following default values apply:
"usageRatingTag": "Usage",
"isBilled": "False",
"ratingAmountType": "Total",
"isTaxExempt": "false",
"offerTariffType": "Normal" |
Create a usage REQUEST | POST usageManagement/usage Content-type: application/json { "date": "2013-04-19T16:42:23-04:00",
"type": "VOICE",
"description": "Description for individual usage content",
"status": "rated",
"usageSpecification": {
"id": "22",
"href": "http://serverlocation:port/usageManagement/usageSpecification/22",
"name": "Voice usage specification"
},
"usageCharacteristic": [
{
"name": "originatingCountryCode",
"value": "43"
}, {
"name": "originatingNumber",
"value": "676123456789"
}, {
"name": "destinationCountryCode",
"value": "49"
}, {
"name": "destinationNumber",
"value": "170123456789"
}, {
"name": "duration",
"value": "20"
}, {
"name": "unit",
"value": "SEC"
}, {
"name": "startDateTime",
"value": "2013-04-19T16:42:23-04:00"
}, {
"name": "endDateTime",
"value": "2013-04-19T16:42:23-04:00"
}
],
"relatedParty": [
{
"role": "serviceProvider",
"id": "1",
"href": "http://serverlocation:port/partyManagement/organization/1"
}, {
"role": "customer",
"id": "45",
"ref": "http://serverlocation:port/partyManagement/individual/45"
}
],
"ratedProductUsage ": [
{
"ratingDate": "2013-04-19T16:42:23-04:00",
"usageRatingTag": "Usage",
"ratingAmountType": "Total",
"taxIncludedRatingAmount": "12.00",
"taxExcludedRatingAmount": "10.00",
"taxRate": "20",
"isTaxExempt": "false",
"offerTariffType": "Normal",
"bucketValueConvertedInAmount": "",
"currencyCode": "EUR"
}
]
} | RESPONSE | 201
Content-Type: application/json
WHOLE RECORD with ID, href |
POST usageManagement/usageSpecification/The resource is used to create usage specification entities.
Attributes: Attribute name | Mandatory | Default | Rule | id | N | Automatically generated | If not given, the id is generated by the system. It is also possible to add an ID in the POST request, which is then used | href | N | Automatically generated | If not given, the href is generated by the system. It is also possible to add an href in the POST request, which is then used | name | N | | | description | N | | | validFor | N | | | usageSpecCharacteristic | N | | |
Rule name | Rule/Pre Condition/Side Effects/Post Conditions | usageSpecCharacteristic | name and usageSpecCharacteristicValue are mandatory | usageSpecCharacteristicValue | valueType is mandatory |
Example REQUEST | POST usageManagement/usageSpecification/ Accept: application/json {{
"id": "22",
"href": "http://serverlocation:port/usageManagement/usageSpecification/22",
"name": "VoiceSpec",
"description": "Spec for voice calls usage",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2099-06-19T00:00:00-04:00"
},
"usageSpecCharacteristic": [
{
"name": "originatingCountryCode",
"description": "country code of the caller",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "originatingNumber",
"description": "phone number of the caller",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "string",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "destinationCountryCode",
"description": "country code of the called party",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "destinationNumber",
"description": "phone number of the called party",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "string",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "duration",
"description": "duration of the call",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "",
"valueFrom": "0",
"valueTo": ""
}
]
}, {
"name": "unit",
"description": "unit of the duration",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "number",
"default": "false",
"value": "SEC",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "startDateTime",
"description": "startdate and starttime of the call",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "dateTime",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}, {
"name": "endDateTime",
"description": "enddate and endtime of the call",
"configurable": "true",
"usageSpecCharacteristicValue": [
{
"valueType": "dateTime",
"default": "false",
"value": "",
"valueFrom": "",
"valueTo": ""
}
]
}
]
} | Example RESPONSE | 201
Content-Type: application/json
(whole record, including ID,href) |
PATCH usagemanagement/USAGEThe resource is used to modify usage entities.
PATCH /usageManagement/usage/{ID}/?{filtering expression}
Attributes and Rules Attribute name | Patchable | Rule | id | N | | href | N | | date | Y | | type | Y | | description | Y | | usageSpecification | Y | | usageCharacteristic | Y | | status | Y | | relatedParty | Y | | ratedProductUsage | Y | |
Rule name | Rule/Pre Condition/Side Effects/Post Conditions | usageCharacteristic | Name and value are mandatory | relatedParty | Role and party are mandatory startDateTime is not mandatory but has a default value -> it is set to sysdate by default | ratedProductUsage | When a usage record is created with a status of rated or billed, the following attributes are mandatory:
"ratingDate", "taxIncludedRatingAmount", "taxExcludedRatingAmount, "taxRate", "currencyCode ", "productRef" | ratedProductUsage | When a usage record is created with a status of rated or billed, the following default values apply:
"usageRatingTag": "Usage",
"isBilled": "False",
"ratingAmountType": "Total",
"isTaxExempt": "false",
"offerTariffType": "Normal" |
Modify a usage
REQUEST A – "rate" a single usage record | PATCH usageManagement/usage/1234/ Content-type: application/json {
"status": "rated",
"ratedProductUsage": [
{
"ratingDate": "2013-04-19T16:42:23-04:00",
"taxIncludedRatingAmount": 22.00,
"taxExcludedRatingAmount": 20.00,
"taxRate": 10,
"currencyCode": "CAD"
}
]
} | RESPONSE | 201
Content-Type: application/json
WHOLE RECORD including ID |
DELETE usagemanagement/USAGESPECificationThe resource is used to DELETE a usage specification entity.
DELETE /usageManagement/usageSpecification/ID/
Delete a usage specification
Deletion of usage specifications is only allowed by specifying the ID in the URL, deleting a single usage specification.
If DELETE is implemented at all, a check must be implemented that verifies that no usage records exist in the system that depend on the usage specification to be deleted – otherwise a 409 (Conflict) HTTP error code should be sent. REQUEST | DELETE usageManagement/usageSpecification/1234/
Content-type: application/json | RESPONSE | 200
Content-Type: application/json |
POST usageManagement/importJobImportJob Tasks are created as resources.
The ImportJob is attached to the URL of the root resource where the content of the file specified by the ImportJob will be applied.
For example to apply the content of the import file located at ftp://ftp.myUsage.com/usage/54 to the usageManagement root. POST usageManagement/exportJobExportJob Tasks are created as resources.
The ExportJob is attached to a specific resource acting as the root for the collection of resources to be streamed to a File.
For example: REQUEST | POST ../usageManagement/exportJob
Content-type: application/json
{
} | RESPONSE | 201 Content-Type: application/json Location: ../usageManagement/exportJob/54 {
"id": "54",
"href": "http:/api/usageManagement/exportJob/54",
"status": "running",
"path": "usageManagement/",
"content-type": "application/json",
"errorLog": "",
"creationDate": "2013-04-19T16:42:23-04:00",
"completionDate": "2013-04-21T16:42:23-04:00",
"url": "ftp://ftp.myUsage.com/usage/54"
} |
GET usageManagement/exportJob
ExportJob resources can be found under the API/exportJob collection and may be retrieved using the normal GET constructs.
For example:
REQUEST | GET ../usageManagement/exportJob/54
Content-type: application/json
{
} | RESPONSE | 200 Content-Type: application/json {
"id": "54",
"href": "http:/api/usageManagement/exportJob/54",
"status": "running",
"path": "usageManagement/",
"content-type": "application/json",
"errorLog": "",
"creationDate": "2013-04-19T16:42:23-04:00",
"completionDate": "2013-04-21T16:42:23-04:00",
"url": "ftp://ftp.myUsage.com/usage/54"
} |
GET usageManagement/IMPORTJob
ImportJob resources can be found under the API/importJob collection and may be retrieved using the normal GET constructs.
For example:
REQUEST | GET ../usageManagement/importJob/54
Content-type: application/json
{
} | RESPONSE | 200 Content-Type: application/json {
"id": "54",
"href": "http:/api/usageManagement/importJob/54",
"status": "running",
"path": "usageManagement/",
"content-type": "application/json",
"errorLog": "",
"creationDate": "2013-04-19T16:42:23-04:00",
"completionDate": "2013-04-21T16:42:23-04:00",
"url": "ftp://ftp.myUsage.com/usage/54"
} |
|