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.
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve BillingAccount (s) in a BillingAccount repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
We mandate L0 (equality) filtering in every specification as per REST Guidelines.
Example: Retrieve BillingAccount 65.
REQUEST |
GET /billingManagement/billingAccount/65 |
RESPONSE |
{ |
| Anchor | ||||
|---|---|---|---|---|
|
No put operation for BillingAccount
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
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.
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.
Attribute name
Patchable
error
RatingType
No
Name
Y
Valid for. startDateTime
Y
Valid for:endDateTime
Y
After the start date
CustomerAccount.id
Y
Should exist
CustomerBillingCycleSpecification.id
Y
CustomerBillFormat.id
Y
CustomerBillPresentationMedia.id
Y
Currency code
Y
PaymentMean.id
Y
RelatedParty.id
Y
Bill receiver is mandatory
State
Y
Transition state should be valid (need further work in financial entities)
BillingAccountBalance
N
No additional complex rules for patching attributes.
Example : Update BillingAccount 65 : change of customer bill presentation media.REQUEST
PATCH billingManagement/billingAccount/65
Content-type: application/json
{
"customerBillPresentationMedia": {
"id": "78",
"href": http://serverlocation:port/billingManagement/customerBillPresentationMedia/78"}
}RESPONSE
201
Content-Type: application/json
{
"customerBillPresentationMedia": {
"id": "78",
"href": http://serverlocation:port/billingManagement/customerBillPresentationMedia/78",
"name": "Paper invoice"
}
}
POST API/bILLING Management/BillingAccountThis operation is used to create a BillingAccount.Anchor _Toc404178548 _Toc404178548
Pre-conditions:
We assume that the customer and the customer account have been already defined. The bill receiver contact also exists.
All reference data have been already defined.
Description :- Provides an overall description of the Operation
- Describes the input representation of the <resource> instance.
- Describes if the resource represents a managed entity or a task.
- Describes the structure of the identifier.
Mandatory attributes are :
Attribute name | Mandatory | Default | error |
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 (see precondition) |
CustomerBillingCycleSpecification.id | N | Bill issuer choice |
|
CustomerBillFormat.id | N | Standard invoice |
|
CustomerBillPresentationMedia.id | N | Electronic invoice |
|
Currency code | N | National currency |
|
PaymentMean | N | Customer choice |
|
RelatedParty.id | Y |
| Bill receiver is mandatory (see precondition) |
BillingAccountBalance.id | N |
|
|
Additional rules
Rule name | Rule |
POST Preconditions | Customer account must have been created previously |
Behavior :
- Standard POST behavior
Example : creation of a BillingAccount
REQUEST |
POST billingManagement/billingAccount |
RESPONSE |
201 |
| Anchor | ||||
|---|---|---|---|---|
|
No delete operation for the BillingAccount.
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
This operation is used to create applied customer billing charges..
Note: Adjustment needs another API to cover invoice adjustment and charge adjustment.
Pre-conditions:
Description :
- Provides an overall description of the Operation
- Describes the input representation of the <resource> instance.
- Describes if the resource represents a managed entity or a task.
- Describes the structure of the identifier.
Mandatory attributes are :
Attribute name | Mandatory | Default | error |
date | N | Today |
|
description | N |
|
|
type | Y |
| Recurring, non recurring, usage, … |
currencyCode | Y |
|
|
taxIncludedAmount | N |
|
|
taxExcludedAmount | Y |
|
|
taxRate.amount | N |
|
|
service.id | Y |
| 400 if service.id is invalid |
service.idType | N |
|
|
productSpecification.name | Y |
|
|
productSpecification.productNumber | N |
|
|
period.startPeriod | N |
| Only mandatory for recurring charge |
period.endPeriod | N |
| Only mandatory for recurring charge |
Additional rules
Rule name | Rule |
POST Preconditions | Service must have been created previously |
Behavior :
- Standard POST behavior
Example : creation of applied customer billing charge
REQUEST |
POST billingManagement/appliedCustomerBillingCharge |
RESPONSE |
201 |
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve AppliedCustomerBillingCharge (s) in a repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
Behavior :
- Standard GET behavior
We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: retrieval of applied customer billing charges
REQUEST |
GET billingManagement/appliedCustomerBillingCharge?service.id=0601020304 |
RESPONSE |
{ |
| Anchor | ||||
|---|---|---|---|---|
|
No delete operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
No patch operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
No put operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve SettlementNoteAdvice (s) in a repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
Behavior :
- Standard GET behavior
We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: get a settlement note advice
REQUEST |
GET billingManagement/settlementNoteAdvice?id=26 |
RESPONSE |
Status:200 |
| Anchor | ||||
|---|---|---|---|---|
|
No delete operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
No patch operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
No put operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
No post operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve CustomerBillingCycleSpecification (s) in a repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
Behavior :
- Standard GET behavior
We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillingCycleSpecification retrieval
REQUEST |
GET billingManagement/customerBillingCycleSpecification/26 |
RESPONSE |
Status:200 |
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve CustomerBillFormat (s) in a repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
Behavior :
- Standard GET behavior
We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillFormat retrieval
REQUEST |
GET billingManagement/customerBillFormat/26 |
RESPONSE |
Status:200 |
| Anchor | ||||
|---|---|---|---|---|
|
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :
- Operation to retrieve CustomerBillPresentationMedia (s) in a repository
- Filtering is enabled for all attributes
- Attribute selection is enabled for all attributes
- The resource is either a managed entity (query by id) or a collection (query with criteria)
- The resource identifier is a http uri
Behavior :
- Standard behavior and response codes for GET operations
Behavior :
- Standard GET behavior
We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillPresentationMedia retrieval
REQUEST |
GET billingManagement/customerBillPresentationMedia/26 |
RESPONSE |
Status:200 |
© TM Forum 2015. All Rights Reserved.