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/troubleTicket/{ID}}/?{fields=attributes}&{filtering expression}
This Uniform Contract operation is used to retrieve the representation of a ticket.
Note that collections can be retrieved via GET /API/troubleTicket/ with no {ID}
Filtering is allowed on all attributes. See example below. Attribute selection is possible for all attributes. See example below.
REQUEST |
GET /api/troubleTicket Accept: application/json |
RESPONSE |
200 Content-Type: application/json [ { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "In Progress", "subStatus": "Held", "statusChangeReason": "Waiting for invoicing expert.", "statusChangeDate": "2013-07-24T08:55:12.0Z", "relatedParty": [ { "href": "/customer/1234", "role": "Originator" }, { "href": "/operator/1234", "role": "Owner" }, { "href": "Roger Collins", "role": "Reviser" } ], "relatedObject": [ { "involvement": "Disputed", "reference": "/invoice/1234" }, { "involvement": "Adjusted", "reference": "/invoice/5678" } ], "note": [ { "date": "2013-07-24T09:55:30.0Z", "author": "Arthur Evans", "text": "Already called the expert" }, { "date": "2013-07-25T08:55:12.0Z", "author": "Arthur Evans", "text": "Informed the originator" } ] }, { "id": "2", "correlationId": "", "description": "Customer asks for information about upgrading products.", "severity": "Low", "type": "Products and Services", "creationDate": "2013-07-25T08:16:00.0Z", "targetResolutionDate": "2013-07-28T00:00:00.0Z", "status": "", "subStatus": "", "statusChangeReason": "", "statusChangeDate": "2013-07-25T08:16:00.0Z", "resolutionDate": "", "relatedParty": [ { "href": "/customer/4567", "role": "Originator" } ], "relatedObject": [ ], "note": [ ] } ] |
Retrieving all tickets – returns an array/ a list of tickets:
Retrieving all tickets which were closed after 2013-05-01:
- GET /api/ticket?status=Close&statusResolutionDate.gt=2013-05-01
Retrieve ticket with specified ID – only one ticket is returned:
Retrieve ticket with ID but only the attributes status and statusChangeReason in the response, separator for attributes is comma:
- GET /api/ticket/1/status,statusChangeReason
PUT API/troubleTicket/{ID}
Description :
- This Uniform Contract operation is used to completely update the representation of a ticket.
- 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 ticket – if you try to change the ticket ID itself an exception is returned. All fields with different values will be changed. If the request contains the same values like the current ticket 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/ troubleTicket/1 Content-type: application/json { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "In Progress", "subStatus": "Held", "statusChangeReason": "Waiting for invoicing expert.", "statusChangeDate": "2013-07-24T08:55:12.0Z", "relatedParty": [ { "href": "/customer/1234", "role": "Originator" }, { "href": "/operator/1234", "role": "Owner" }, { "href": "Roger Collins", "role": "Reviser" } ], "relatedObject": [ { "involvement": "Disputed", "reference": "/invoice/1234" }, { "involvement": "Adjusted", "reference": "/invoice/5678" } ], "note": [ { "date": "2013-07-24T09:55:30.0Z", "author": "Arthur Evans", "text": "Already called the expert" }, { "date": "2013-07-25T08:55:12.0Z", "author": "Arthur Evans", "text": "Informed the originator" } ] } |
RESPONSE |
201 Content-Type: application/json { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "In Progress", "subStatus": "Held", "statusChangeReason": "Waiting for invoicing expert.", "statusChangeDate": "2013-07-24T08:55:12.0Z", "relatedParty": [ { "href": "/customer/1234", "role": "Originator" }, { "href": "/operator/1234", "role": "Owner" }, { "href": "Roger Collins", "role": "Reviser" } ], "relatedObject": [ { "involvement": "Disputed", "reference": "/invoice/1234" }, { "involvement": "Adjusted", "reference": "/invoice/5678" } ], "note": [ { "date": "2013-07-24T09:55:30.0Z", "author": "Arthur Evans", "text": "Already called the expert" }, { "date": "2013-07-25T08:55:12.0Z", "author": "Arthur Evans", "text": "Informed the originator" } ] } |
Example see TMF REST Design Guidelines.
PATCH API/troubleTicket/{ID}
Description :
- This Uniform Contract operation is used to partially update the representation of a ticket.
- Resource represents a managed entity.
Behavior :
Patching of status is only allowed to transition :
- from "resolved" to "closed",
- from "created", "acknowledged" or "in progress" to "cancelled"
Patching of relatedParties[], relatedObjects[] or notes[] replaces previous value set.
Attribute name | Patchable | Rule |
id | N | |
correlationId | N | |
description | Y | |
severity | Y | |
type | Y | |
creationDate | N | |
targetResolutionDate | Y | |
status | Y | |
subStatus | Y | |
statusChangeReason | Y | |
statusChangeDate | Y | |
resolutionDate | Y | |
relatedParty | Y | |
relatedObject | Y | |
note | Y | |
Further document any rules that must be implemented when patching attributes.
Rule name | Rule/Pre Condition/Side Effects/Post Conditons |
To be completed | To be completed |
REQUEST |
PATCH API/ troubleTicket /{ID} Content-type: application/json { "status": "Close", "statusChangeReason": "Dispute has been resolved in favor of the customer." } |
RESPONSE |
201 Content-Type: application/json { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "Closed", "subStatus": "", "statusChangeReason": "Dispute has been resolved in favor of the customer.", "statusChangeDate": "2013-07-24T08:55:12.0Z", "relatedParty": [ { "href": "/customer/1234", "role": "Originator" }, { "href": "/operator/1234", "role": "Owner" }, { "href": "Roger Collins", "role": "Reviser" } ], "relatedObject": [ { "involvement": "Disputed", "reference": "/invoice/1234" }, { "involvement": "Adjusted", "reference": "/invoice/5678" } ], "note": [ { "date": "2013-07-24T09:55:30.0Z", "author": "Arthur Evans", "text": "Already called the expert" }, { "date": "2013-07-25T08:55:12.0Z", "author": "Arthur Evans", "text": "Informed the originator" } ] } |
POST API/ticket
Description :
- This Uniform Contract operation is used to create a ticket.
- Resource represents a managed entity.
- Mandatory attributes that must be provided when you create the ticket :
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, …).
Attribute name | Mandatory | Default | Rule |
Id | N | | Initialized by TT handler |
correlationId | N | | |
description | Y | | |
severity | Y | | |
type | Y | | |
creationDate | N | Date of the day | Initialized by TT handler |
targetResolutionDate | N | | |
status | N | Created | Initialized by TT handler |
subStatus | N | | |
statusChangeReason | N | | |
statusChangeDate | N | Date of the day | |
resolutionDate | N | | |
relatedParty | N | | |
relatedObject | N | | |
Note | N | | |
Further specify any rules on the creation of the entity
Rule name | Rule |
To be completed | To be completed |
The requester should not provide an id – it is generated automatically by the TT handler. A correlationId can be provided, but is not mandatory.
Create a ticket only with mandatory attributes:
REQUEST |
POST API/ troubleTicket Content-type: application/json { "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment" } |
RESPONSE |
201 Content-Type: application/json { "id": "1", "correlationId": "TT53482", "description": "Customer complaint over last invoice.", "severity": "Urgent", "type": "Bills, charges or payment", "creationDate": "2013-07-23T08:16:39.0Z", "targetResolutionDate": "2013-07-30T10:20:01.0Z", "status": "Created", "subStatus": "", "statusChangeReason": "", "statusChangeDate": "2013-07-24T08:55:12.0Z", "resolutionDate": "", "relatedParty": [ ], "relatedObject": [ ], "note": [ ] } |