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 /customerManagement/customer/{ID}
Note that collections can be retrieved via GET /customerManagement/customer without ID. In that case an array of customers is returned.
Description:
- This operation retrieves collection of customers (array) or only one customer when specifying the ID in the URI.
- Filtering is enabled on all attributes
- Attribute selection is enabled
- The resource represents one managed entity or a collection depending on the query pattern
- The identifier is a string that can consist of numbers, not necessarily alphanumeric
Behavior:
- Return Status Codes
- 200 OK – the request was successful (includes criteria where the filtering condition didn't match to any records)
- 400 Bad Request – Error
- 404 If no record was found for the supplied criteria
- 500 The server encountered an unexpected condition which prevented it from fulfilling the request
REQUEST
GET /customerManagement/customer/{ID}/?{fields=attributes}&{filtering expression}
Accept: application/jsonRESPONSE
Status:200
Content-Type: application/json
{
"id": "c1234",
"href": "http://serverlocation:port/customerManagement/customer/c1234",
"name": "DisplayName",
"status": "Active",
"description": "Description string",
"validFor": {
"startDateTime": "2013-06-19T04:00:00.0Z",
"endDateTime": "2013-04-19T20:42:23.0Z"
},
"customerRank": "3",
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1",
"role": "customer",
"name": "John Doe"
},
"characteristic": [
{
"name": "characteristicname1",
"value": "characteristicvalue1"
},
{
"name": "characteristicname2",
"value": "characteristicvalue2"
}
],
"contactMedium": [
{
"type": "Email",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"emailAddress": "[email protected]"
}
},
{
"type": "PostalAddress",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"city": "Wien",
"country": "Austria",
"postcode": "1020",
"stateOrProvince": "Quebec",
"street1": "Lassallestrasse7",
"street2": ""
}
},
{
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"type": "mobile",
"number": "+436641234567"
}
},
{
"preferred": true,
"type": "TelephoneNumber",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z"
},
"medium": {
"type": "business",
"number": "+436641234567"
}
}
],
"customerAccount": [
{
"id": "1",
"href": "http://serverlocation:port/customerManagement/customerAccount/1",
"name": "CustomerAccount1",
"description": "CustomerAccountDesc1",
"accountStatus": "Active"
},
{
"id": "2",
"href": "http://serverlocation:port/customerManagement/customerAccount/2",
"name": "CustomerAccount2",
"description": "CustomerAccountDesc2",
"accountStatus": "Active"
}
],
"customerCreditProfile": [
{
"creditProfileDate": "2013-04-19T20:42:23.0Z",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z",
"endDateTime": "2013-06-19T04:00:00.0Z"
},
"creditRiskRating": 1,
"creditScore": 1
},
{
"creditProfileDate": "2013-04-19T20:42:23.0Z",
"validFor": {
"startDateTime": "2013-04-19T20:42:23.0Z",
"endDateTime": "2013-06-19T04:00:00.0Z"
},
"creditRiskRating": 1,
"creditScore": 1
}
],
"paymentMean": [
{
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "my favourite payment mean"
},
{
"id": "64",
"href": "http://serverlocation:port/customerManagement/paymentMean/64",
"name": "my credit card payment mean"
}
]
}
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
Accept: application/jsonRESPONSE
Status: 200
Content-Type: application/json
{
"id": "c1234",
"href": "http://serverlocation:port/customerManagement/customer/c1234",
"name": "DisplayName",
"status": "Active",
"customerAccount": [
{
"id": "1",
"href": "http://serverlocation:port/customerManagement/customerAccount/1",
"name": "CustomerAccount1",
"description": "CustomerAccountDesc1",
"accountStatus": "Active"
},
{
"id": "2",
"href": "http://serverlocation:port/customerManagement/customerAccount/2",
"name": "CustomerAccount2",
"description": "CustomerAccountDesc2",
"accountStatus": "Active"
}
]
}
REQUEST
GET /customerManagement/customer?fields=id,name ,validFor&status=Active&validFor.startDateTime.gt=2013-05-05
Accept: application/jsonRESPONSE
Status: 200
Content-Type: application/json
[
{
"id": "c1234",
"name": "DisplayName",
"validFor": {
"startDateTime": "2013-06-06T16:42:23.0Z",
"endDateTime": ""
}
},
{
"id": "c1234",
"name": "DisplayName",
"validFor": {
"startDateTime": "2013-08-09T16:42:23.0Z",
"endDateTime": ""
}
}
]PUT /customerManagement/customer/{ID}
This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
Description:
- This operation is used to completely update a customer
- The resource represents a managed entity.
- The identifier is a string that can consist of numbers, not necessarily alphanumeric
Behavior:
- Return Status Codes:
- 200 Customer data modified successfully
- 400 Bad Request Error
- 404 If no record was found for the supplied criteria
- 500 The server encountered an unexpected condition which prevented it from fulfilling the request
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 |
PATCH API/customerManagement/customer/{ID}
This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description:
- Patch operation can be used partially update one or more customers
- The resource represents a managed entity or a collection
- The identifier is a string that can consist of numbers, not necessarily alphanumeric
Behavior:
- Return Status Codes:
- 200 – Customer(s) data modified successfully
- 400 – Bad Request Error
- 404 - If no record was found for the supplied criteria
- 500 - The server encountered an unexpected condition which prevented it from fulfilling the request
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 |
POST /customerManagement/customer
This Uniform Contract operation is used to create a customer.
Description:
- This operation is used to create one customer
- The identifier is a string that can consist of numbers, not necessarily alphanumeric
- The mandatory element(s) is/are
- Customer Name
- The id is generated automatically
Behavior:
- Return Status Codes:
- 201 Customer create successfully. The Content-Location Header must be set and can be used to retrieve the customer
- 400 Bad Request Error
- 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/
Content-type: application/json
{
"name": "DisplayName"
}RESPONSE
Status:201
Content-Type: application/json
Content-Location: http://serverlocation:port/customerManagement/customer/c123423243
{
"id": "c123423243",
"name": "DisplayName",
"status": "New",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": ""
}
}
The below query pattern can be used to create a single customer with more attributes:REQUEST
POST /customerManagement/customer/
Content-type: application/json
{
"name": "DisplayName",
"customerRank": 3,
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1"
},
"contactMedium": [
{
"type": "Email",
"medium": {
"emailAddress": "[email protected]"
}
}, {
"preferred": true,
"type": "TelephoneNumber",
"medium": {
"type": "business",
"number": "+436641234567"
}
}
],
"customerCreditProfile": [
{
"creditProfileDate": "2013-04-19T16:42:23-04:00",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"creditRiskRating": "1",
"creditScore": "1"
}, {
"creditProfileDate": "2013-04-19T16:42:23-04:00",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"creditRiskRating": "1",
"creditScore": "1"
}
]
}RESPONSE
Status:201
Content-Type: application/json
Content-Location: http://serverlocation:port/customerManagement/customer/c1234
{
"id": "c1234",
"name": "DisplayName",
"status": "New",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": ""
},
"customerRank": 3,
"relatedParty": {
"id": "1",
"href": "http://serverlocation:port/partyManagement/individual/1"
},
"contactMedium": [
{
"type": "Email",
"medium": {
"emailAddress": "[email protected]"
}
}, {
"preferred": true,
"type": "TelephoneNumber",
"medium": {
"type": "business",
"number": "+436641234567"
}
}
],
"customerCreditProfile": [
{
"creditProfileDate": "2013-04-19T16:42:23-04:00",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"creditRiskRating": "1",
"creditScore": "1"
}, {
"creditProfileDate": "2013-04-19T16:42:23-04:00",
"validFor": {
"startDateTime": "2013-04-19T16:42:23-04:00",
"endDateTime": "2013-06-19T00:00:00-04:00"
},
"creditRiskRating": "1",
"creditScore": "1"
}
]
}DELETE /customerManagement/customer/{ID}
This Uniform Contract operation is used to delete a managed entity or a task.
Description:
- This operation is used to delete customer(s) using customer id(s)
- The resource represents a managed entity
- The identifier is a string that can consist of numbers, not necessarily alphanumeric
Behavior:
- Return Status Codes:
- 204 – NO Content. Customer Deleted successfully
- 400 – Bad Request Error
- 404 – Customer Data Not Found
- 500 - The server encountered an unexpected condition which prevented it from fulfilling the request
REQUEST |
DELETE /customerManagement/customer/c1234 |
RESPONSE |
Status:204 |
GET customerManagement/customerAccount/{ID}
Note that collections can be retrieved via GET /customerManagement /customerAccount with no {ID}
Description :
- This operation returns all customerAccounts, unless an ID is specified in which case a specific customerAccount resource would be returned.
- The resource instance being returned is a customerAccount or an array of customerAccounts if the query returns multiple resources
- Filtering is enabled on all customerAccount attributes.
- Attribute selection is enabled.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 200 OK – customer account was retrieved
- 404 Not found when the supplied ID doesn't match a known customerAccount.
- 500 Internal server Error
- Returns HTTP/1.1 status code 200 if the request was successful.
- Any other special return and/or exception codes.
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 customerManagement/customerAccount/{ID}
PUT is not supported for customerAccount as any modification can be handled through PATCH API.
PATCH customerManagement/customerAccount/{ID}
Description :
- This Uniform Contract operation is used to partially update the representation of a customer account.
- Resource represents the customer account.
- Behavior :
- Update of customer account will be based on identifier( id)
- Update of customer account is allowed to all attributes except attributes which are set by backend and are read-only (id, lastModified, etc.)
- Update of name, accountType, status, creditLimit is allowed through PATCH API.
- After creation of customer accout using mandatory parameters(mentoned in POST API),Update / linking of customer[], financialcharge[], relatedParty[], paymentPlan[] should be possible through PATCH.
- Child customer account can also be linked/updated to the parent customer by updating customerAccountRelationship[] in customerAccount resource.
- The resource instance being returned is a customerAccount
Behavior :
- Returns HTTP/1.1 status code 200 if the request was successful.
- Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).
- 500 – Internal server Error
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 |
POST customerManagement/customerAccount/{ID}
Description :
- This Uniform Contract operation is used to create a customer account.
- Resource represents a managed entity.
- The resource instance being returned is a customerAccount
- Mandatory attributes that must be provided when you create the customer account :
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, …).
- 500 – Internal server Error
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 |
DELETE customerManagement/customerAccount/{ID}
Note customer account will be deleted via DELETE /customerAccount/{ID} and will not allow deletion of customers if no id is provided.
Description:
- This operation will delete the customer Account with the specified ID
- The return will be response code and will not have any resource.
- Attribute selection is disabled.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 404 Not found when the supplied ID doesn't match a known customerAccount.
- Returns HTTP/1.1 status code 204 if the request was successful.
- 500 – Internal server Error
The following example shows deletion of customer account with filtration criteria based on id.
REQUEST |
DELETE /customerManagement/customerAccount/ca1234 |
RESPONSE |
Status:204 |
GET customerManagement/paymentMean/{ID}
Note that collections can be retrieved via GET /customerManagement /paymentMean with no {ID}
Description :
- This operation returns all paymentMean, unless an ID is specified in which case a specific paymentMean resource would be returned.
- The resource instance being returned is a paymentMean or an array of paymentMean if the query returns multiple resources
- Filtering is enabled on all paymentMean attributes.
- Attribute selection is enabled.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 200 OK – paymentMean was retrieved
- 404 Not found when the supplied ID doesn't match a known paymentMean.
- 500 Internal server Error
- Returns HTTP/1.1 status code 200 if the request was successful.
- Any other special return and/or exception codes.
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 customerManagement/paymentMean/{ID}
PUT is not supported for paymentMean as any modification can be handled through PATCH API.
PATCH customerManagement/paymentmean/{ID}
Description :
- This Uniform Contract operation is used to partially update the representation of a payment mean.
- Resource represents the payment mean.
- Behavior :
- Update of paymentMean will be based on identifier( id)
- Update of paymentMean is allowed to all attributes except attributes which are set by backend and are read-only (id, href, etc.)
- Update of name, validFor is allowed through PATCH API.
Behavior :
- Returns HTTP/1.1 status code 200 if the request was successful.
- Returns HTTP/1.1 status code 400 (Bad request) if content is invalid (missing required attributes, …).
- 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}
Content-type: application/json-patch+json
{
"op": "update",
"path": "/customerAccount/paymentMean",
"value": {
"name": "new name for my credit card"
}
}RESPONSE
Status:200
Content-Type: application/json
{ JSON Resource Representation with every attributes }POST customerManagement/paymentmean/{ID}
Description : - This Uniform Contract operation is used to create a payment mean.
- Resource represents a managed entity.
- The resource instance being returned is a paymentMean
- Mandatory attributes that must be provided when you create the paymentMean :
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, …).
- 500 – Internal server Error
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 |
DELETE customerManagement/paymentMean/{ID}
Note payment mean will be deleted via DELETE /paymentMean/{ID} and will not allow deletion of paymentMean if no id is provided.
Description:
- This operation will delete the paymentMean with the specified ID
- The return will be response code and will not have any resource.
- Attribute selection is disabled..
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 404 Not found when the supplied ID doesn't match a known paymentMean.
- Returns HTTP/1.1 status code 204 if the request was successful.
- 500 – Internal server Error
The following example shows deletion of paymentMean with filtration criteria based on id.
REQUEST |
DELETE /customerManagement/customerAccount/45 |
RESPONSE |
Status:204 |