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.
This Uniform Contract operation is used to retrieve the representation of a managed entity or a task.
Note that collections can be retrieved via GET api/SLA with no {ID}
Description :
Behavior :
Specify what level of attribute filtering can be used. In fact we mandate L0 (equality) filtering in every specification as per REST Guidelines. Add this to Template.
REQUEST |
GET /api/sla |
RESPONSE |
200 |
Retrieving all SLAs – returns an array/ a list of SLAs:
Retrieving all SLAs where 'http://..//acme.com' is involved with "SLAProvider" role:
Retrieving all SLAs where 'http://…//mycompany.com' is involved with "SLAConsumer" role:
Retrieving all SLAs where 'http://…//John.Doe' is involved with "EndUser" role:
Retrieving all SLAs based on template '"http/www.acme.com/slaManagement/slaTemplate/42":
Retrieve sla with specified ID – only one SLA is returned:
This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
Description :
Behavior :
Description:
Behavior:
Updating the whole SLA – if you try to change the SLA ID itself an exception is returned. All fields with different values will be changed. If the request contains the same values like the current SLA representation, nothing is changed. If an element is empty in the request, the value of the element will be deleted. If it is a required element, an exception is returned.
REQUEST |
PUT API/SLA/1 |
RESPONSE |
201 |
Description:
Table of patchable attributes
Attribute name | Patchable | Rule |
id | N |
|
name | Y |
|
description | Y |
|
version | Y |
|
validityPeriod | Y |
|
template | Y |
|
href | Y |
|
name | Y |
|
description | Y |
|
relatedParty | Y |
|
state | Y |
|
approved | Y |
|
rules | Y |
|
id | Y |
|
metric | Y |
|
unit | Y |
|
referenceValue | Y |
|
operator | Y |
|
tolerance | Y |
|
Consequence | Y |
|
Further document any rules that must be implemented when patching attributes. It is use-case driven
Rule name | Rule/Pre Condition/Side Effects/Post Conditons |
|
|
|
|
REQUEST |
PATCH API/sla/{ID} |
RESPONSE |
201 |
Description:
Description, severity, type
Behavior:
The requester cannot generate the id – the id to identify the REST resource is generated automatically in the back-end. The correlationId can be set from external but is not mandatory.
Specify the attributes required when an entity is created (and their default values if not):
Attribute name | Mandatory | Default | Rule |
id | N |
|
|
name | Y |
|
|
description | N |
|
|
version | N |
|
|
validityPeriod | N |
|
|
template | N |
|
|
href | N |
|
|
name | N |
|
|
description | N |
|
|
relatedParty | N |
|
|
state | N |
|
|
approved | N |
|
|
rules | N |
|
|
id | N |
|
|
metric | N |
|
|
unit | N |
|
|
referenceValue | N |
|
|
operator | N |
|
|
tolerance | N |
|
|
Consequence | N |
|
|
Further specify any rules on the creation of the entity
Rule name | Rule |
|
|
|
|
REQUEST |
POST API/sla |
RESPONSE |
201 |
Behavior :
Any other special return and/or exception codes.
REQUEST |
DELETE API/SLA/{ID} |
RESPONSE |
200 |
Example see TMF REST Design Guidelines.
© TM Forum 2015. All Rights Reserved