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 /catalogManagement/category
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/<RESOURCE> with no {ID}
Description :
- This operation retrieves productCategory from a catalog. The category resource is used to group product offerings, service and resource candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.
- The resource represents a managed entity or a collection depending on the query pattern.
- The identifier is a string that can consist of numbers, not necessarily alphanumeric.
Behavior :
- Standard behavior and response codes for GET operations
- Filtering is enabled on all attributes, particularly due to the hierarchical nature of productCategory, children of a productCategory are obtained by filtering on the parentId attribute of the resource.
- Attribute selection is not enabled for this simple resource
REQUEST
GET /catalogManagement/category/{42}
Accept: application/jsonRESPONSE
200
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/category/42", "lastUpdate": "2013-04-19T16:42:23-04:00", "version": "2.0", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "parentId": " 41", "isRoot": "false", "name": "Cloud Services", "description": "A category to hold all available cloud service offers" }GET /catalogManagement/productOffering/{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/<RESOURCE> with no {ID}
Description : - This operation returns all productOfferings from the catalog, unless an ID is specified in which case a specific productOffering resource would be returned. The ProductOffering resource represents entities that are orderable from the provider of the catalog. This resource includes pricing information.
- The resource instance being returned is a productOffering or an array of product offering if the query returns multiple resources
- The resource is either a managed entity or a collection depending on the query pattern.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 200 if no productOffering found for supplied categoryId (200) (filter expression)
- 404 Not found when the supplied ID doesn't match a known productOffering.
- Filtering is enabled on all productOffering attributes.
- Attribute selection is enabled.
REQUEST
GET /catalogManagement/productOffering/{42}
Accept: application/jsonRESPONSE
200
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "version": "2.0", "lastUpdate": "2013-04-19T16:42:23-04:00", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "category": [ {
"id": "12",
"href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ {
"id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" } ], "place": [ {
"id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" } ], "bundledProductOffering": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": {
"id": "28",
"href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": { "id": "13",
"href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" },
"serviceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" },
"resourceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" },
"productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" } } ], "productOfferingPrice": [ { "name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "monthly" }, { "name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "" } ] }
Another example of a query on the category.href attribute would be executed, however only a limited set of attributes is initially returned (id, name, description, productSpecification and validFor).REQUEST
GET /catalogManagement/productOffering/name,id,description,validFor,productSpecification,isBundle,bundledProductOffering?category.id=12
Accept: application/jsonRESPONSE for bundled ProductOffering
200
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "bundledProductOffering": [ {
"id": "15",
"href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "productSpecification": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" } }RESPONSE for simple ProductOffering
200
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "false", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" },
"productSpecification": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" } }GET /catalogManagement/productSpecification/{ID}
This Uniform Contract operation is used to retrieve the representation of a managed entity or collection.
Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description : - This operation returns productSpecifications from a catalog. A detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to Customers or other Parties playing a PartyRole.
- The resource instance being returned is a productSpecification or an array of productSpecifications if the query returns multiple specifications.
- The resource represents a managed entity or a collection.
- The ID may be a string (or a string containing numbers).
Behavior :
- What status and exception codes are returned.
- 200 if no productSpecification found
- 404 Not found when the supplied ID doesn't match a known productSpecification.
- Filtering is enabled on all productSpecification attributes.
- Attribute selection is enabled.
REQUEST
GET /catalogManagement/productSpecification/22
Accept: application/jsonRESPONSE
{ "id": "22", "href": "http://serverlocation:port/catalogManagement/productSpecification/22", "productNumber": "WS45-230-FC", "version": "2.0", "lastUpdate": "2013-04-19T16:42:23-04:00", "name": "iPhone 42", "description": "Siri works on this iPhone", "isBundle": "true", "brand": "Apple", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "relatedParty": [ {
"id": "1234", "role": "Owner", "href": "http ://serverLocation:port/partyManagement/partyRole/1234" } ], "attachment": [ {
"id": "22", "href": "http://serverlocation:port/documentManagement/attachment/22", "type": "Picture", "url": "http://xxxxx" } ], "bundledProductSpecification": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productSpecification/15", "lifecycleStatus": "Active", "name": "Product specification 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productSpecification/64", "lifecycleStatus": "Active", "name": "Product specification 64" } ], "productSpecificationRelationship": [ { "id": "23",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/23",
"type": "dependency", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ], "serviceSpecification": [ {
"id": "13", "href": "http://serverlocation:port/catalogManagement/serviceSpecification/13", "name": "specification 1", "version": "1.1" } ], "resourceSpecification": [ {
"id": "13", "href": "http://serverlocation:port/catalogManagement/resourceSpecification/13", "name": "specification 1", "version": "1.1" } ], "productSpecCharacteristic": [ { "name": "Screen Size", "description": "Screen size", "valueType": "number", "configurable": "false", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" },
"productSpecCharacteristicValue": [ { "valueType": "number", "default": "true", "value": "4.2", "unitOfMeasure": "inches", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] }, {
"name": "Colour", "description": "Colour", "valueType": "string", "configurable": "true", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "productSpecCharacteristicValue": [ { "valueType": "string", "default": "true", "value": "Black", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } }, { "valueType": "string", "default": "false", "value": "White", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] } ] }PUT /catalogManagement/category/{ID}
This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
Description : - This operation completely updates a category.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
REQUEST
PUT /catalogManagement/category/42
Content-type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/category/42", "lastUpdate": "2013-04-19T16:42:23-04:00", "version": "2.0", "lifecycleStatus": "Launched", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "parentId": " 41", "isRoot": "false", "name": "Cloud Services", "description": "A category to hold all available cloud service offers" }RESPONSE
201
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/category/42", "lastUpdate": "2013-04-25T09:28:10-04:00", "version": "2.0", "lifecycleStatus": "Launched", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "parentId": "41", "isRoot": "false", "name": "Cloud Services", "description": "A category to hold all available cloud service offers" }
PUT /catalogManagement/productOffering/{ID}
This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
Description : - This operation completely updates a productOffering.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
REQUEST
PUT /catalogManagement/productOffering/42
Content-type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "version": "2.0", "lastUpdate": "2013-04-19T16:42:23-04:00", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "category": [ {
"id": "12", "href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ {
"id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" }, {
"id": "14", "href": "http://serverlocation:port/marketSales/channel/14", "name": "Shop" } ], "place": [ { "id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" }, { "id": "14", "href": "http://serverlocation:port/marketSales/place/14", "name": "Belgium" } ], "bundledProductOffering": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": {
"id": "28", "href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" },
"serviceCandidate": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" },
"resourceCandidate": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" },
"productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" } } ], "productOfferingPrice": [ {
"name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "monthly" }, {
"name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "" } ] }RESPONSE
201
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "version": "3.0", "lastUpdate": "2013-06-05T08:30:45-04:00", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "category": [ {
"id": "12", "href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ {
"id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" }, {
"id": "14", "href": "http://serverlocation:port/marketSales/channel/14", "name": "Shop" } ], "place": [ {
"id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" }, {
"id": "14", "href": "http://serverlocation:port/marketSales/place/14", "name": "Belgium" } ], "bundledProductOffering": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": {
"id": "28", "href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" },
"serviceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" },
"resourceCandidate": {
"id": "13", "href": "http://serverlocation:port/catalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" },
"productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" } } ], "productOfferingPrice": [ {
"name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "monthly" }, {
"name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "" } ] }PUT /catalogManagement/productSpecification
This Uniform Contract operation is used to completely update the representation of a managed entity or a task.
Description : - This operation completely updates a productSpecification.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
REQUEST
PUT /catalogManagement/productSpecification
Content-type: application/json
{ "id": "22", "href": "http://serverlocation:port/catalogManagement/productSpecification/22", "version": "2.0", "lastUpdate": "2013-04-19T16:42:23-04:00", "name": "iPhone 42", "description": "Siri works on this iPhone", "isBundle": "true", "brand": "Apple", "lifecycleStatus": "Launched", "validFor": { "startDateTime": "2013-06-20T16:42:23-04:00", "endDateTime": "" }, "relatedParty": [ {
"id": "1234", "role": "Owner", "href": "http ://serverLocation:port/partyManagement/partyRole/1234" } ], "attachment": [ {
"id": "22", "href": "http://serverlocation:port/documentManagement/attachment/22", "type": "Picture", "url": "http://xxxxx" } ], "bundledProductSpecification": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productSpecification/15", "lifecycleStatus": "Launched", "name": "Product specification 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productSpecification/64", "lifecycleStatus": "Launched", "name": "Product specification 64" } ], "productSpecificationRelationship": [ { "type": "dependency",
"id": "23", "href": " http://serverlocation:port/catalogManagement/productSpecification/23", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ], "serviceSpecification": [ {
"id": "13", "href": "http://serverlocation:port/catalogManagement/serviceSpecification/13", "name": "specification 1", "version": "1.1" } ], "resourceSpecification": [ { "id": "13", "href": "http://serverlocation:port/catalogManagement/resourceSpecification/13", "name": "specification 1", "version": "1.1" } ], "productSpecCharacteristic": [ { "name": "Screen Size", "description": "Screen size", "valueType": "number", "configurable": "false", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "productSpecCharacteristicValue": [ { "valueType": "number", "default": "true", "value": "4.2", "unitOfMeasure": "inches", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] }, { "name": "Colour", "description": "Colour", "valueType": "string", "configurable": "true", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "productSpecCharacteristicValue": [ { "valueType": "string", "default": "true", "value": "Black", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } }, { "valueType": "string", "default": "false", "value": "White", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] } ] }RESPONSE
201
Content-Type: application/json
{ "id": "22", "href": "http://serverlocation:port/catalogManagement/productSpecification/22", "version": "2.0", "lastUpdate": "2013-06-20T16:42:23-04:00", "name": "iPhone 42", "description": "Siri works on this iPhone", "isBundle": "true", "brand": "Apple", "lifecycleStatus": "Launched", "validFor": { "startDateTime": "2013-06-20T16:42:23-04:00", "endDateTime": "" }, "relatedParty": [ {
"id": "1234", "role": "Owner", "href": "http ://serverLocation:port/partyManagement/partyRole/1234" } ], "attachment": [ {
"id": "22", "href": "http://serverlocation:port/documentManagement/attachment/22", "type": "Picture", "url": "http://xxxxx" } ], "bundledProductSpecification": [ {
"id": "15", "href": "http://serverlocation:port/catalogManagement/productSpecification/15", "lifecycleStatus": "Launched", "name": "Product specification 15" }, {
"id": "64", "href": "http://serverlocation:port/catalogManagement/productSpecification/64", "lifecycleStatus": "Launched", "name": "Product specification 64" } ], "productSpecificationRelationship": [ { "type": "dependency",
"id": "23", "href": " http://serverlocation:port/catalogManagement/productSpecification/23", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ], "serviceSpecification": [ {
"id": "13", "href": "http://serverlocation:port/catalogManagement/serviceSpecification/13", "name": "specification 1", "version": "1.1" } ], "resourceSpecification": [ {
"id": "13", "href": "http://serverlocation:port/catalogManagement/resourceSpecification/13", "name": "specification 1", "version": "1.1" } ], "productSpecCharacteristic": [ { "name": "Screen Size", "description": "Screen size", "valueType": "number", "configurable": "false", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "productSpecCharacteristicValue": [ { "valueType": "number", "default": "true", "value": "4.2", "unitOfMeasure": "inches", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] }, { "name": "Colour", "description": "Colour", "valueType": "string", "configurable": "true", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "productSpecCharacteristicValue": [ { "valueType": "string", "default": "true", "value": "Black", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } }, { "valueType": "string", "default": "false", "value": "White", "unitOfMeasure": "", "valueFrom": "", "valueTo": "", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" } } ] } ] }PATCH /catalogManagement/category/{ID}
This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description : - This operation partially updates a category.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
Specify which attributes are patchable using the following table (to capture RO attributes)
Attribute name |
Patchable |
Rule |
Id |
No |
|
lastUpdate |
No |
|
version |
Y |
Should be greater than the current one |
lifecycleStatus |
Y |
Status should be valid |
startDateTime |
Y |
|
endDateTime |
Y |
Should be greater than startDateTime |
parentId |
Y |
The parent category should exist |
isRoot |
Y |
To be updated in compliance with the parentId |
name |
Y |
|
description |
Y |
|
Further document any rules that must be implemented when patching attributes.
Rule name |
Rule/Pre Condition/Side Effects/Post Conditons |
Root |
When isRoot is patched to false, parentId should indicate the parent category. |
REQUEST |
PATCH /catalogManagement/category/{42} |
RESPONSE |
201 |
PATCH /catalogManagement/productOffering/{ID}
This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description :
- This operation partially updates a productOffering.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
Specify which attributes are patchable using the following table (to capture RO attributes)
Attribute name |
Patchable |
Rule |
Id |
No |
|
lastUpdate |
No |
|
version |
Y |
Should be greater than the current one |
lifecycleStatus |
Y |
Status should be valid |
startDateTime |
Y |
|
endDateTime |
Y |
Should be greater than startDateTime |
isBundle |
Y |
To be updated in compliance with the bundledProductOffering |
name |
Y |
|
description |
Y |
|
category |
Y |
|
bundledProductOffering |
Y |
To be updated in compliance with isBundle |
productSpecification |
Y |
It should exist |
serviceCandidate |
Y |
It should exist |
resourceCandidate |
Y |
It should exist |
channel |
Y |
It should exist |
place |
Y |
It should exist |
productOfferingTerm |
Y |
|
productOfferingPrice |
Y |
It should exist |
Further document any rules that must be implemented when patching attributes.
Rule name |
Rule/Pre Condition/Side Effects/Post Conditons |
isBundle |
isBundle determines whether a productOffering represents a single productOffering (false), or a bundle of productOfferings (true). |
REQUEST |
PATCH /catalogManagement/productOffering/{42} |
RESPONSE |
201 |
PATCH /catalogManagement/productSpecification/{ID}
This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description :
- This operation partially updates a productSpecification.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
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.
Specify which attributes are patchable using the following table (to capture RO attributes)
Attribute name |
Patchable |
Rule |
Id |
No |
|
lastUpdate |
No |
|
version |
Y |
Should be greater than the current one |
lifecycleStatus |
Y |
Status should be valid |
startDateTime |
Y |
|
endDateTime |
Y |
Should be greater than startDateTime |
isBundle |
Y |
To be updated in compliance with the bundledProductSpecification |
name |
Y |
|
description |
Y |
|
brand |
Y |
|
relatedParty |
Y |
It should exist |
attachment |
Y |
It should exist |
bundledProductSpecification |
Y |
To be updated in compliance with isBundle |
productSpecificationRelationship |
Y |
It should exist |
serviceSpecification |
Y |
It should exist |
resourceSpecification |
Y |
It should exist |
productSpecCharacteristic |
Y |
It should exist |
productSpecCharacteristicValue |
Y |
|
Further document any rules that must be implemented when patching attributes.
Rule name |
Rule/Pre Condition/Side Effects/Post Conditons |
isBundle |
isBundle determines whether a productSpecification represents a single productSpecification (false), or a bundle of productSpecification (true). |
REQUEST |
PATCH /catalogManagement/productSpecification/{22} |
RESPONSE |
201 |
POST /catalogManagement/category
This Uniform Contract operation is used to create a managed entity or a task.
Description :
- This operation creates a category
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
Behavior :
- Standard POST behavior.
- Returns HTTP/1.1 status code 201 if the request was successful.
- Any other special return and/or exception codes.
ID Management :
The response provide the category id.
Specify the attributes required when an entity is created (and their default values if not):
Attribute name |
Mandatory |
Default |
Rule |
isRoot |
N |
true |
|
name |
Y |
|
|
parentId |
Y |
|
If isRoot is set to "false", parentId is mandatory |
- Further specify any rules on the creation of the entity
Rule name
Rule
REQUEST
POST catalogManagement/category
Content-type: application/json
{
"version": "1.0", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "parentid": "http://serverlocation:port/catalogManagement/category/42",
"isRoot": "false", "name": "Cloud Services", "description": "A category to hold all available cloud service offers" }RESPONSE
201
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/category/42", "lastUpdate": "2013-04-19T16:42:23-04:00", "version": "1.0", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "" }, "parentid": "http://serverlocation:port/catalogManagement/category/42",
"isRoot": "false", "name": "Cloud Services", "description": "A category to hold all available cloud service offers" }POST /catalogManagement/productOffering
This Uniform Contract operation is used to create a managed entity or a task.
Description : - This operation creates a productOffering
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
Behavior :
- Standard POST behavior.
- Returns HTTP/1.1 status code 201 if the request was successful.
- Any other special return and/or exception codes.
ID Management :
The response provides the productOffering id.
Specify the attributes required when an entity is created (and their default values if not):
Attribute name |
Mandatory |
Default |
Rule |
name |
Y |
|
|
isBundle |
N |
false |
|
bundledProductOffering |
Y |
|
If isBundle is set to "true", bundledProductOffering is mandatory |
productSpecification |
Y |
|
|
productOfferingPrice |
Y |
|
|
- Further specify any rules on the creation of the entity
Rule name
Rule
REQUEST
POST catalogManagement/productOffering
Content-type: application/json
{
"version": "1.0",
"name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "category": [ { "id": "12", "href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ { "id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" } ], "place": [ { "id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" } ], "bundledProductOffering": [ { "id": "15", "href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, { "id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": { "id": "28", "href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": { "id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" },
"serviceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" },
"resourceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" },
"productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" } } ], "productOfferingPrice": [ {
"name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "monthly" }, {
"name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "" } ] }RESPONSE
201
Content-Type: application/json
{ "id": "42", "href": "http://serverlocation:port/catalogManagement/productOffering/42", "version": "1.0", "lastUpdate": "2013-04-19T16:42:23-04:00", "name": "Virtual Storage Medium", "description": "Virtual Storage Medium", "isBundle": "true", "lifecycleStatus": "Active", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "category": [ { "id": "12", "href": "http://serverlocation:port/catalogManagement/category/12", "version": "2.0", "name": "Cloud offerings" } ], "channel": [ { "id": "13", "href": "http://serverlocation:port/marketSales/channel/13", "name": "Online Channel" } ], "place": [ { "id": "12", "href": "http://serverlocation:port/marketSales/place/12", "name": "France" } ], "bundledProductOffering": [ { "id": "15", "href": "http://serverlocation:port/catalogManagement/productOffering/15", "lifecycleStatus": "Active", "name": "Offering 15" }, { "id": "64", "href": "http://serverlocation:port/catalogManagement/productOffering/64", "lifecycleStatus": "Active", "name": "Offering 64" } ], "serviceLevelAgreement": { "id": "28", "href": "http://serverlocation:port/slaManagement/serviceLevelAgreement/28", "name": "Standard SLA" }, "productSpecification": { "id": "13", "href": "http://serverlocation:port/catalogManagement/productSpecification/13", "version": "2.0", "name": "specification product 1" },
"serviceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/serviceCandidate/13", "version": "2.0", "name": "specification service 1" },
"resourceCandidate": { "id": "13", "href": "http://serverlocation:port/catalogManagement/resourceCandidate/13", "version": "2.0", "name": "specification resource 1" },
"productOfferingTerm": [ { "name": "12 Month", "description": "12 month contract", "duration": "12", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" } } ], "productOfferingPrice": [ {
"name": "Monthly Price", "description": "monthlyprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "recurring", "unitOfMeasure": "", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "monthly" }, {
"name": "Usage Price", "description": "usageprice", "validFor": { "startDateTime": "2013-04-19T16:42:23-04:00", "endDateTime": "2013-06-19T00:00:00-04:00" }, "priceType": "usage", "unitOfMeasure": "second", "price": { "taxIncludedAmount": "12.00", "dutyFreeAmount": "10.00", "taxRate": "20.00", "currencyCode": "EUR" }, "recurringChargePeriod": "" } ] }POST /catalogManagement/productSpecification
This Uniform Contract operation is used to create a managed entity or a task.
Description : - This operation creates a productSpecification.
- The resource represents a managed entity.
- The ID may be a string (or a string containing numbers).
Behavior :
- Standard POST behavior.
- Returns HTTP/1.1 status code 201 if the request was successful.
- Any other special return and/or exception codes.
ID Management :
The response provides the productSpecification id.
Specify the attributes required when an entity is created (and their default values if not):
Attribute name |
Mandatory |
Default |
Rule |
name |
Y |
|
|
isBundle |
N |
false |
|
bundledProductSpecification |
Y |
|
If isBundle is set to "true", bundledProductSpecification is mandatory |
productSpecCharacteristic |
Y |
|
|
productSpecCharacteristicValue |
Y |
|
|
- Further specify any rules on the creation of the entity
Rule name
Rule
REQUEST
POST catalogManagement/productSpecification
Content-type: application/json
{
"productNumber": "I42-340-DX",
"version": "2.0",
"lastUpdate": "2013-04-19T16:42:23.0Z",
"name": "iPhone 42",
"description": "Siri works on this iPhone",
"isBundle": true,
"brand": "Apple",
"lifecycleStatus": "Active",
"validFor":
{
"startDateTime": "2013-06-19T00:00:00.0Z",
"endDateTime": "2013-04-19T16:42:23.0Z"
},
"relatedParty":
[
{
"id": "1234",
"href": "http ://serverLocation:port/partyManagement/partyRole/1234",
"role": "Owner"
}
],
"attachment":
[
{
"id": "22",
"href": "http://serverlocation:port/documentManagement/attachment/22",
"type": "Picture",
"url": "http://xxxxx"
}
],
"bundledProductSpecification":
[
{
"id": "15",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/15",
"lifecycleStatus": "Active",
"name": "Product specification 15"
},
{
"id": "64",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/64",
"lifecycleStatus": "Active",
"name": "Product specification 64"
}
],
"productSpecificationRelationship":
[
{
"id": "23",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/23",
"type": "dependency",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"serviceSpecification":
[
{
"id": "13",
"href": "http://serverlocation:port/serviceCatalogManagement/serviceSpecification/13",
"name": "specification 13",
"version": "1.1"
}
],
"resourceSpecification":
[
{
"id": "13",
"href": "http://serverlocation:port/resourceCatalogManagement/resourceSpecification/13",
"name": "specification 13",
"version": "1.1"
}
],
"productSpecCharacteristic":
[
{
"name": "Screen Size",
"description": "Screen size",
"valueType": "number",
"configurable": false,
"ProductSpecCharacteristicValue":
[
{
"valueType": "number",
"default": true,
"value": "4.2",
"unitOfMeasure": "inches",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
},
{
"name": "Colour",
"description": "Colour",
"valueType": "string",
"configurable": true,
"ProductSpecCharacteristicValue":
[
{
"valueType": "string",
"default": true,
"value": "Black",
"unitOfMeasure": "",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
},
{
"valueType": "string",
"default": false,
"value": "White",
"unitOfMeasure": "",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
]
}RESPONSE
201
Content-Type: application/json
{
"id": "22",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/22",
"productNumber": "I42-340-DX",
"version": "2.0",
"lastUpdate": "2013-04-19T16:42:23.0Z",
"name": "iPhone 42",
"description": "Siri works on this iPhone",
"isBundle": true,
"brand": "Apple",
"lifecycleStatus": "Active",
"validFor":
{
"startDateTime": "2013-06-19T00:00:00.0Z",
"endDateTime": "2013-04-19T16:42:23.0Z"
},
"relatedParty":
[
{
"id": "1234",
"href": "http ://serverLocation:port/partyManagement/partyRole/1234",
"role": "Owner"
}
],
"attachment":
[
{
"id": "22",
"href": "http://serverlocation:port/documentManagement/attachment/22",
"type": "Picture",
"url": "http://xxxxx"
}
],
"bundledProductSpecification":
[
{
"id": "15",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/15",
"lifecycleStatus": "Active",
"name": "Product specification 15"
},
{
"id": "64",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/64",
"lifecycleStatus": "Active",
"name": "Product specification 64"
}
],
"productSpecificationRelationship":
[
{
"id": "23",
"href": "http://serverlocation:port/productCatalogManagement/productSpecification/23",
"type": "dependency",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"serviceSpecification":
[
{
"id": "13",
"href": "http://serverlocation:port/serviceCatalogManagement/serviceSpecification/13",
"name": "specification 13",
"version": "1.1"
}
],
"resourceSpecification":
[
{
"id": "13",
"href": "http://serverlocation:port/resourceCatalogManagement/resourceSpecification/13",
"name": "specification 13",
"version": "1.1"
}
],
"productSpecCharacteristic":
[
{
"name": "Screen Size",
"description": "Screen size",
"valueType": "number",
"configurable": false,
"ProductSpecCharacteristicValue":
[
{
"valueType": "number",
"default": true,
"value": "4.2",
"unitOfMeasure": "inches",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
},
{
"name": "Colour",
"description": "Colour",
"valueType": "string",
"configurable": true,
"ProductSpecCharacteristicValue":
[
{
"valueType": "string",
"default": true,
"value": "Black",
"unitOfMeasure": "",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
},
{
"valueType": "string",
"default": false,
"value": "White",
"unitOfMeasure": "",
"valueFrom": "",
"valueTo": "",
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
],
"validFor":
{
"startDateTime": "2013-04-19T16:42:23.0Z"
}
}
]
}
POST catalogManagement/importJob
ImportJob Tasks are created as resources.
The ImportJob is attached to the URL of the root resource where the content of the file specified by the ImportJob will be applied.
For example to apply the content of the import file located at ftp://ftp.myCatalog.com/catalog.json to the catalogManagement root.REQUEST
POST ../partyManagement/importJob
Content-type: application/json
{
"url": "ftp://ftp.myCatalog.com/catalog.json"
}RESPONSE
201
Content-Type: application/json
Location: ../partyManagement/importJob/554
{ "id": "54", "href": "http:/api/catalogManagement/importJob/54", "status": "running", "path": "catalogManagement/", "content-type": "application/json", "errorLog": "", "creationDate": "2013-04-19T16:42:23-04:00",
"url": "ftp://ftp.myCatalog.com/catalog.json" }
POST catalogManagement/exportJob
ExportJob Tasks are created as resources.
The ExportJob is attached to a specific resource acting as the root for the collection of resources to be streamed to a File.
An ExportJob can be attached to a specific Resource in the Catalog Management application for example: - ../catalogManagement/exportJob
Export all the resources within catalogManagement subject to query and path assignments.
- ../catalogManagement/catalog/2/exportJob
Export all the resources within the catalog with "id" = 2 subject to query and path assignments.
For example:
REQUEST |
POST ../catalogManagement/exportJob |
RESPONSE |
201 |
GET catalogManagement/exportJob
ExportJob resources can be found under the API/exportJob collection and may be retrieved using the normal GET constructs for individual resources or queries on the exportJob collection i.e GET ../catalogManagement/exportJob/?(name=value)*
For example:
REQUEST |
GET ../catalogManagement/exportJob/54 |
RESPONSE |
200 |
GET catalogManagement/importJob
ImportJob resources can be found under the API/importJob collection and may be retrieved using the normal GET constructs for individual resources or queries on the importJob collection. GET ../catalogManagement/importJob/?(name=value)*
For example:
REQUEST |
GET ../catalogManagement/importJob/54 |
RESPONSE |
200 |
DELETE API/{RESOURCE}/{ID}
No delete operations
This Uniform Contract operation is used to delete a managed entity or a task.
Description :
- Provide an overall description of the Operation
- 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 200 if the request was successful.
- Any other special return and/or exception codes.
REQUEST
DELETE API/{RESOURCE}/{ID}
RESPONSE
200
Example see TMF REST Design Guidelines.