Remember the following Uniform Contract:
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 /orderManagement/productOrder/{ID}
Note that collections can be retrieved via GET /orderManagement/productOrder with no {ID}
Description :
This operation is used to retrieve order information using the ID
Attribute selection is enabled on all first level attributes but not on inner classes.
Attribute selection may optionally be enabled on all attributes and inner classes.
Behavior :
- Return status codes
- 200 OK - the request was successful
- 404 Not found - the supplied ID does not match a known productOrder
Use case : Get a specific order based on its ID
REQUEST |
GET /orderManagement/productOrder/42 |
RESPONSE |
200 |
GET /orderManagement/productOrder/?{field selector}&{filtering expression}
Description :
This operation is used to retrieve order information using filter criteria.
Filtering selection is enabled on all first level attributes but not on inner classes with the exception of relatedParties.
Filtering may optionally be enabled on all attributes and inner classes.
Attribute selection is enabled on all first level attributes but not on inner classes.
Attribute selection may optionally be enabled on all attributes and inner classes.
Behavior :
- Return status codes
- 200 OK - the request was successful (includes situation in which no orders matched supplied criteria)
- 400 Bad Request - error
Use case : Get all the orders for a given customer that were completed before a specified date
REQUEST |
GET /orderManagement/productOrder?relatedParty.role=customer& relatedParty.id=345221&completionDate.lt=2013-09-10 T00:00:00 -04:00 |
RESPONSE |
200 |
PATCH /orderManagement/productOrder/{ID}
Description :
This operation is used to modify orders and/or their items.
Behavior :
- Return status codes
- 200 OK - the request was successful
- 400 Bad Request - error
Attribute name |
Patchable |
Rule |
id |
No |
|
href |
No |
|
externalID |
No |
|
state |
Yes |
To manage the order delivery process : InProgress (start process), Held / Pending (suspend process) |
priority |
Yes |
|
category |
Yes |
|
orderDate |
No |
|
requestedStartDate |
Yes |
Only when order is in "Acknowledged" state – delivery process not started |
completionDate |
No |
|
requestedCompletionDate |
Yes |
Only when order is in "Acknowledged" state – delivery process not started |
expectedCompletionDate |
Yes |
|
notificationContact |
Yes |
|
note |
Yes |
|
relatedParty |
Yes |
Only when order is in "Acknowledged" state – delivery process not started |
orderItem.id |
No |
|
orderItem.action |
No |
|
orderItem.state |
Yes |
To manage the order item delivery process : InProgress (start sub process), Held / Pending (suspend sub process) |
orderItem.billingAccount |
Yes |
Only when order is in "Acknowledged" state – delivery process not started |
orderItem.productOffering |
Yes |
Only when order is in "Acknowledged" state – delivery process not started |
orderItem.product |
Yes |
Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended |
orderItem.product.place |
Yes |
Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended |
orderItem.appointment |
Yes |
Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended |
Further document any rules that must be implemented when patching attributes.
Rule name |
Rule/Pre Condition/Side Effects/Post Conditons |
State patches |
When patching an order state to :
|
Use case : Resume order
Note : Suspend would be the same request using the "Pending" state.
REQUEST |
PATCH orderManagement/productOrder/42 |
RESPONSE |
201 |
POST orderManagement/productorder
Description:
This operation is used to create a new order.
The mandatory attributes for the creation are :
- relatedParties.role and reference to identify at least the customer
- at least one orderItem with :
- an action
- a productOffering
Behavior :
- Return status codes
- 201 Created - the request was successful
- 400 Bad Request – error
ID Management :
POST should be used without specifying the id and the href, the OM system is in charge of generating the id + href for the ProductOrder.
When performing a POST, these are the allowed attributes (all Product Order attributes that are not in that list MUST NOT be used during POST, they are calculated/defined by the OM system) :
Attribute name |
Mandatory |
Default |
Rule |
externalID |
N |
N/A |
|
state |
N |
"Acknowledged" |
|
priority |
N |
4 (the lowest) |
|
Description |
N |
N/A |
|
category |
N |
"uncategorized" |
|
requestedStartDate |
N |
No specified default value |
|
requestedCompletionDate |
N |
No specified default value |
|
notificationContact |
N |
No specified default value |
|
note |
N |
No specified default value |
|
relatedParty |
Y |
|
They must be at least a defined party linked to the order (Customer, …) |
orderItem.id |
Y |
|
|
orderItem.action |
Y |
|
|
orderItem.state |
N |
"Acknowledged" |
|
orderItem.billingAccount |
Y |
|
|
orderItem.productOffering |
N |
|
The productOffering may not be useful when doing a "modify" or "delete" on an owned product |
orderItem.product |
Y |
|
|
orderItem.product.place |
N |
|
|
orderItem.appointment |
N |
|
|
- Further specify any rules on the creation of the entity
Rule name
Rule
POST Mandatory attributes within product Order
-
- Within "billingAccount"
- Within "billingAccount"
-
- id AND/OR href
- id AND/OR href
- Within "note"
- text
- text
- Within "relatedParty"
- id AND/OR href AND/OR name
- role|
POST Mandatory attributes within product Order item
-
- Within "place"
- Within "place"
-
- Role
- id AND/OR href
- id AND/OR href AND/OR name
- Within "productOffering"
- id AND/OR href
- id AND/OR href
- Within "product"
- Depends on the order item "action", cf. rule below|
POST Mandatory attributes within product (in each order item)
-
- If orderItem.action = "add" :
- If orderItem.action = "add" :
-
- productCharacteristics
- Depends on the order item "action", cf. rule below|
- If orderItem.action = "modify"
- id AND/OR href
- id AND/OR href
- If orderItem.action = "delete"
- id AND/OR href|
REQUEST
POST /orderManagement/productOrder
Content-type: application/json
{ "note":[ { "text":"A free text detailing the note" } ], "relatedParty":[ { "role":"customer", "id":"345221", "href":"http://serverlocation:port/partyManagement/customer/345221", "name":"John Doe" }, { "role":"seller", "id":"4563", "href":"http://serverlocation:port/partnerManagement/partner/4563" } ], "orderItem":[ { "id":"1", "action":"add", "billingAccount":[{ "id":"1789", "href":"http://serverlocation:port/billingManagement/billingAccount/1789" }], "productOffering":{ "id":"42", "href":"http: //serverlocation: port/catalogManagement/productOffering/42" }, "product":{ "productCharacteristic":[ { "name":"Colour", "value":"White" }, { "name":"Memory", "value":"16" } ] } }, { "id":"2", "action":"modify", "product":{ "id":"456", "href":"http: //serverlocation: port/inventoryManagement/product/456", "relatedParty":[ { "role":"user", "id":"5667443", "href":"http://serverlocation:port/partyManagement/user/5667443", "name":"Jimmy Doe" } ] } }, { "id":"3", "action":"delete", "product":{ "id":"456", "href":"http: //serverlocation: port/inventoryManagement/product/456" } } ]}RESPONSE
201
Content-Type: application/json
{ "id":"42", "href":"http://serverlocation:port/orderManagement/productOrder/42", "priority":"4", "category":"uncategorized", "state":"Acknowledged", "orderDate":"2013-04-12T16:42:23-04:00", "expectedCompletionDate":"2013-04-19T16:42:23-04:00", "note":[ { "text":"A free text detailing the note" } ], "relatedParty":[ { "role":"customer", "id":"345221", "href":"http://serverlocation:port/partyManagement/customer/345221" "name":"John Doe" }, { "role":"seller", "id":"4563", "href":"http://serverlocation:port/partnerManagement/partner/4563" } ], "orderItem":[ { "id":"1", "action":"add", "state":"Acknowledged", "billingAccount":[{ "id":"1789", "href":"http://serverlocation:port/billingManagement/billingAccount/1789" }], "productOffering":{ "id":"42", "href":"http: //serverlocation: port/catalogManagement/productOffering/42" }, "product":{ "productCharacteristic":[ { "name":"Colour", "value":"White" }, { "name":"Memory", "value":"16" } ] } }, { "id":"2", "action":"modify", "state":"Acknowledged", "product":{ "id":"456", "href":"http: //serverlocation: port/inventoryManagement/product/456", "relatedParty":[ { "role":"user", "id":"5667443", "href":"http://serverlocation:port/partyManagement/user/5667443", "name":"Jimmy Doe" } ] } }, { "id":"3", "action":"delete", "state":"Acknowledged", "product":{ "id":"456", "href":"http: //serverlocation: port/inventoryManagement/product/456" } } ]}
DELETE orderManagement/productorder/{ID}
This operation is used to delete a managed entity or a product order entirely.
Warning : it should only be used for administration matters
Description :
This operation is used to delete an order.
The only usable and also mandatory attributes for the deletion are id AND/OR href.
Behavior :
- id AND/OR href|
-
- Returns HTTP/1.1 status code 200 if the request was successful.
- 404 if the product order does not exist
- 403 if the operation is forbidden
REQUEST
DELETE /orderManagement/productOrder/5868839
RESPONSE
200