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.
Note that collections can be retrieved via GET /customerManagement/customer without ID. In that case an array of customers is returned.
Description:
Behavior:
500 The server encountered an unexpected condition which prevented it from fulfilling the request
REQUEST |
GET /customerManagement/customer/{ID}/?{fields=attributes}&{filtering expression} |
RESPONSE |
Status:200 |
If we need to retrieve only limited set of attributes and also filter the records based on certain filters then the below query pattern:
REQUEST |
GET /customerManagement/customer/c1234?fields=id,name,status,customerAccount |
RESPONSE |
Status: 200 |
REQUEST |
GET /customerManagement/customer?fields=id,name ,validFor&status=Active&validFor.startDateTime.gt=2013-05-05 |
RESPONSE |
Status: 200 |
Behavior:
The below query pattern can be used to modify all the data for a single customer, if an attribute is not provided, the value of the attribute is deleted:
REQUEST |
PUT /customerManagement/customer/{ID} |
RESPONSE |
Status: 200 |
This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description:
Behavior:
Patchable attributes:
Attribute name | Patchable | Rule |
id | N |
|
name | Y |
|
status | Y |
|
description | Y |
|
validFor | Y |
|
customerRank | Y |
|
relatedParty | Y |
|
characteristic | Y |
|
contactMedium | Y |
|
customerAccount | Y |
|
customerCreditProfile | Y |
|
paymentMean | Y |
|
Rules:
Rule name | Rule/Pre Condition/Side Effects/Post Conditions |
party | id is mandatory |
characteristic | name and value are mandatory |
contactMedium | type and medium are mandatory |
customerAccount | id, name and accountStatus are mandatory |
customerCreditProfile | creditProfileDate and validFor are mandatory |
paymentMean | Id, href are mandatory |
Update of single attributes. In the following the name and the customerRank are updated. The request just consists of the two attributes with its new values. The response includes all attributes.
REQUEST |
PATCH /customerManagement/customer/c1234 |
RESPONSE |
Status: 200 |
PATCH update for an array
REQUEST |
PATCH /customerManagement/customer/c1234 |
RESPONSE |
Status: 200 |
This Uniform Contract operation is used to create a customer.
Description:
Behavior:
500 The server encountered an unexpected condition which prevented it from fulfilling the request
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 |
name | Y |
|
|
status | N |
|
|
description | N |
|
|
validFor | N |
|
|
customerRank | N |
|
|
party | N |
|
|
characteristic | N |
|
|
contactMedium | N |
|
|
customerAccount | N |
|
|
customerCreditProfile | N |
|
|
paymentMean | N |
|
|
Rules:
Rule name | Rule/Pre Condition/Side Effects/Post Conditions |
relatedParty | ref is mandatory |
characteristic | name and value are mandatory |
contactMedium | type and medium are mandatory |
customerAccount | id, name and accountStatus are mandatory |
customerCreditProfile | creditProfileDate and validFor are mandatory |
paymentMean | Id, href are mandatory |
The below query pattern can be used to create a single customer only the mandatory attributes:
REQUEST |
POST /customerManagement/customer/ |
RESPONSE |
Status:201 |
The below query pattern can be used to create a single customer with more attributes:
REQUEST |
POST /customerManagement/customer/ |
RESPONSE |
Status:201 |
Behavior:
REQUEST |
DELETE /customerManagement/customer/c1234 |
RESPONSE |
Status:204 |
Note that collections can be retrieved via GET /customerManagement /customerAccount with no {ID}
Description :
Behavior :
Examples: Get request with one customer including all attributes in the response. Filtering and attribute selection is described in the examples following.
REQUEST |
GET /customerManagement/customerAccount/{ID}/?{fields=attributes}&{filtering expression} |
RESPONSE |
{ |
In order to address a specific query a list of customer, with only a subset of the attributes in the response, the query pattern would look like the following:
REQUEST |
GET /customerManagement/customerAccount/?fields=name,id,accountType,status, creditLimit,pin&accountType="residential" |
RESPONSE for Customer Account |
Status:200 |
In order to address a specific query against the Primary customer account (having an id) of an hierarchical account structure and also to reflect the hierarchy, the query pattern in this case would be as follows:
REQUEST |
GET /customerManagement/customerAccount/ca1234?fields=name,id,accountType, accountStatus,creditLimit,pin,customerAccountRelationship |
RESPONSE for Customer Account |
{ |
In order to address a specific query against those customer accounts which have been modified after a certain date time, the query pattern in this case would be as follows:
REQUEST |
GET /customerManagement/customerAccount/?fields=name,id,accountType, accountStatus,creditLimit,pin,lastModified&lastModified.gt="2013-08-08" |
RESPONSE for Customer Account |
Status:200 |
PUT is not supported for customerAccount as any modification can be handled through PATCH API.
Description :
Behavior :
Note: -The requester cannot update the id. The lastModified attributes is updated automatically in the back-end.
Attribute name | Patchable | Rule |
id | N | Cannot be updated from outside |
lastModified | N | Is updated automatically |
name | Y |
|
accountType | Y |
|
status | Y |
|
description | Y |
|
creditLimit | Y |
|
pin | Y |
|
receivableBalance | Y |
|
customerAccountTaxExemption | Y |
|
customerAccountRelationship | Y |
|
contact | Y |
|
customer | Y |
|
customerAccountBalance | Y |
|
paymentPlan | Y |
|
paymentMean | Y |
|
Rule name | Rule/Pre Condition/Side Effects/Post Conditions |
customerAccountTaxExemption | issuingJurisdiction and validFor are mandatory |
customerAccountRelationship | relationshipType and validFor are mandatory |
contact | contactType and validFor are mandatory |
customer | id and name are mandatory |
customerAccountBalance | id, type, amount, validFor and status are mandatory |
paymentPlan | id, status, amount, paymentFrequency and validFor as well as paymentMean are mandatory |
paymentMean | Id, href are mandatory |
Eg: PATCH for adding a new customerAccountTaxExemption to customer account.
REQUEST |
PATCH /customerManagement/customerAccount/{ID} |
RESPONSE |
Status:200 |
PATCH of accountType in customerAccount resource
REQUEST |
PATCH/customerManagement/customerAccount/ca1234 |
RESPONSE |
Status:200 |
Description :
Behavior :
The requester cannot generate the id. The id and lastModified attributes are generated automatically in the back-end.
Required Attributes: Name, AccountType
Read-Only Attributes: id, lastModified, receivableBalance, customerAccountBalance
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 |
lastModified | N | Automatically generated | Cannot be set from outside |
name | Y |
|
|
accountType | Y |
|
|
status | N |
|
|
description | N |
|
|
creditLimit | N |
|
|
pin | N |
|
|
receivableBalance | N |
|
|
customerAccountTaxExemption | N |
|
|
customerAccountRelationship | N |
|
|
contact | N |
|
|
customer | N |
|
|
customerAccountBalance | N |
|
|
paymentPlan | N |
|
|
paymentMean | N |
|
|
Rules:
Rule name | Rule/Pre Condition/Side Effects/Post Conditons |
customerAccountTaxExemption | issuingJurisdiction and validFor are mandatory |
customerAccountRelationship | relationshipType and validFor are mandatory |
contact | contactType and validFor are mandatory |
customer | id and name are mandatory |
customerAccountBalance | id, type, amount, validFor and status are mandatory |
paymentPlan | id, status, amount, paymentFrequency and validFor are mandatory |
paymentMean | Id, href are mandatory |
Create a customer account only with mandatory attributes:
REQUEST |
POST customerManagement/customerAccount/{ID} |
RESPONSE |
Status:201 |
Note customer account will be deleted via DELETE /customerAccount/{ID} and will not allow deletion of customers if no id is provided.
Description:
Behavior :
The following example shows deletion of customer account with filtration criteria based on id.
REQUEST |
DELETE /customerManagement/customerAccount/ca1234 |
RESPONSE |
Status:204 |
Note that collections can be retrieved via GET /customerManagement /paymentMean with no {ID}
Description :
Behavior :
Examples: Get request with one payment mean including all attributes in the response. Filtering and attribute selection is described in the examples following.
REQUEST |
GET /customerManagement/paymentMean/{ID}/?{fields=attributes}&{filtering expression} |
RESPONSE |
{ |
|---|
PUT is not supported for paymentMean as any modification can be handled through PATCH API.
Description :
Behavior :
500 – Internal server Error
Attribute name | Patchable | Rule |
id | N | Cannot be updated from outside |
href | N | Cannot be updated from outside |
name | Y |
|
validFor | Y |
|
Rule name | Rule/Pre Condition/Side Effects/Post Conditions |
|
|
Eg: PATCH for updating the name.
REQUEST |
PATCH /customerManagement/customerAccount/{ID} |
RESPONSE |
Status:200 |
Behavior :
The requester cannot generate the id. The id is generated automatically in the back-end.
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 | Cannot be set from outside |
name | Y |
|
|
paymentMeanType | Y |
|
|
relatedParty | Y |
|
|
bankAccount | N |
|
|
creditCard | N |
|
|
Rules:
Rule name | Rule/Pre Condition/Side Effects/Post Conditions |
bankAccount | Mandatory if paymentMeanType is different from Credit card |
creditCard | Mandatory is paymentMeanType is equal to Credit card |
Create a customer account only with mandatory attributes:
REQUEST |
POST customerManagement/paymentMean/{ID} |
RESPONSE |
Status:201 |
Note payment mean will be deleted via DELETE /paymentMean/{ID} and will not allow deletion of paymentMean if no id is provided.
Description:
Behavior :
The following example shows deletion of paymentMean with filtration criteria based on id.
REQUEST |
DELETE /customerManagement/customerAccount/45 |
RESPONSE |
Status:204 |