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/SLA/{ID}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 : - Provide an overall description of the Operation
- Describe the returned representation of the <resource> instance(s).
- Describe if filtering is enabled and what can be done using query parameters.
- Describe if attribute selection is enabled.
- Describe if the resource represents a managed entity, a collection or a task.
- Describe the structure of the identifier.
Behavior : - What status and exception codes are returned.
- Returns HTTP/1.1 status code 200 if the request was successful.
- Any other special return and/or exception codes.
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
Accept: application/json | RESPONSE | 200
Content-Type: application/json
{"sla": [
JSON Resource Representation with every attributes }]
} |
Retrieving all SLAs – returns an array/ a list of SLAs:
- GET /api/sla
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: PUT API/SLA/{ID}This Uniform Contract operation is used to completely 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.
Description: - This Uniform Contract operation is used to completely update the representation of a SLA.
- Resource represents a managed entity.
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, …).
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
Content-type: application/json
{"sla": { JSON Resource Representation with every attributes }} | RESPONSE | 201
Content-Type: application/json
{"sla": { JSON Resource Representation with every attributes } |
PATCH API/SLA/{ID}Description: - This Uniform Contract operation is used to partially update the representation of a SLA.
- Resource represents a managed entity.
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}
Content-type: application/json
{"sla": {
JSON Resource Representation with every attributes }} | RESPONSE | 201
Content-Type: application/json
{"sla": { JSON Resource Representation with every attributes }} |
POST API/SLA/{ID}Description: - This Uniform Contract operation is used to create a SLA.
- Resource represents a managed entity.
- Mandatory attributes that must be provided when you create the SLA :
Description, severity, type
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, …).
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 | | |
Behavior : |