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 API/billingManagement/ BillingAccount /{ID}
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 |
{ |
PUT API/BillingManagement/BillingAccount/{ID}
No put operation for BillingAccount
PATCH API/billingManagement/ BillingAccount /{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.
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/BillingAccount
This operation is used to create a BillingAccount.
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 |
DELETE API/billingManagement/BillingAccount/{ID}
No delete operation for the BillingAccount.
REQUEST |
|
RESPONSE |
|
POST API/bILLING Management/AppliedCustomerbillingcharge
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 |
GET API/bILLING Management/AppliedCustomerbillingcharge
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 |
{ |
DELETE API/billingManagement/ appliedCustomerBillingCharge /{ID}
No delete operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
PATCH API/billingManagement/ appliedCustomerBillingCharge /{ID}
No patch operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
PUT API/billingManagement/ appliedCustomerBillingCharge /{ID}
No put operation for the AppliedCustomerBillingCharge
REQUEST |
|
RESPONSE |
|
GET API/bILLINGManagement/SettlementnoteADVICE /{ID}
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 |
DELETE API/billingManagement/ Settlement note ADVICE /{ID}
No delete operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
PATCH API/billingManagement/ Settlement note ADVICE /{ID}
No patch operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
PUT API/billingManagement/ Settlement note ADVICE /{ID}
No put operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
POST API/billingManagement/ Settlement note ADVICE /{ID}
No post operation for the SettlementNoteAdvice
REQUEST |
|
RESPONSE |
|
GET API/bILLING Management/ CUSTOMER BILLING CYCLE Specification
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 |
GET API/bILLING Management/ CUSTOMER BILL Format
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 |
GET API/bILLING Management/ CUSTOMER BILL Presentation Media
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 |