Page tree

 

SERVICE CATALOG MANAGEMENT

REST SPECIFICATION TEMPLATE

 

Document Number:  <###>

Document Version: : <V1.6.5.0.4>

Date: October, 2016

Document Status: Draft

NOTICE

Copyright © TeleManagement Forum 2016. All Rights Reserved.

 

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE ..............................................................................................................................................................................

Table of Contents ..............................................................................................................................................................

List of Tables

Introduction .........................................................................................................................................................................

SAMPLE USE CASES .....................................................................................................................................................

Lifecycle Management Use Case

Order management Use Case

RESOURCE MODEL .......................................................................................................................................................

Managed Entity and Task Resource Models

Service Catalog

Category

Service Candidate

Service Specification

Notification Resource Models ......................................................................................................................................................

API OPERATION TEMPLATES .....................................................................................................................................

GET /catalogManagement/serviceCatalog/{ID}

GET /catalogManagement/category

GET /catalogManagement/serviceCandidate/{ID}

GET /catalogManagement/serviceSpecification/{ID}

GET /catalogManagement/exportJob/{ID}

GET /catalogManagement/importJob/{ID}

GET/…depth

PUT /catalogManagement/serviceCatalog/{ID}

PUT /catalogManagement/category/{ID}

PUT /catalogManagement/serviceCandidate/{ID}

PUT /catalogManagement/serviceSpecification/{ID}

PATCH /catalogManagement/serviceCatalog/{ID}

PATCH /catalogManagement/category/{ID}

PATCH /catalogManagement/serviceCandidate/{ID}

PATCH /catalogManagement/serviceSpecification/{ID}

POST /catalogManagement/category/{ID}

POST /catalogManagement/serviceCandidate/{ID}

POST /catalogManagement/serviceSpecification/{ID}

POST /catalogManagement/catalog/{10}/importJob

POST /catalogManagement/catalog/{10}/exportJob

DELETE API/{RESOURCE}/{ID} ................................................................................................................................................

API NOTIFICATION TEMPLATES .................................................................................................................................

REGISTER LISTENER POST /hub ............................................................................................................................................

UNREGISTER LISTENER DELETE hub/{id}

publish {EventTYPE} POST /listener ..........................................................................................................................................

LIFECYCLE MANAGEMENT EXTENSIONS TO CATALOG ....................................................................................

Query all versioned catalog resources .......................................................................................................................................

Query a specific versioned CATALOG resource ......................................................................................................................

Query current version of a catalog resource .............................................................................................................................

Create new version OF A CATALOG resource ........................................................................................................................

Modify an existing version OF A CATALOG resource ............................................................................................................

Role based Access Control ..........................................................................................................................................................

Release History ..............................................................................................................................................................................

 

List of Tables

 

Aucune entrée de table d'illustration n'a été trouvée.

 

Introduction

The following document is the template for the REST API documentation.

The catalog management API allows the management of the entire lifecycle of the catalog elements, the consultation of catalog elements during several processes such as ordering process, campaign management, sales management…

SAMPLE USE CASES

Lifecycle Management Use Case [KM1]

The Service Catalog Management API allows the management of the entire lifecycle of the service catalog elements.

UC1: A partner updates its catalog, and notifies the distributor of the catalog change. The distributor requests a catalog export and retrieves the catalog at the provided URL.

UC2: A partner updates its catalog and notifies all catalog changes in detail to the distributor. The distributor then updates its copy of the catalog by following the changes.

UC3: A catalog administrator wants to retrieve effective duration of a service candidate by ID (GET/serviceCandidate/:id).

UC4: A catalog administrator wants to retrieve all available service candidates (GET/serviceCandidate).

UC5: A catalog administrator wants to update the lifecycle status (from Launched to retired for example) of a service candidate (PUT or PATCH/serviceCandidate).

Order management Use Case

The service catalog management API allows the lookup of the catalog elements during order capture.

UC1: The provider wants to browse resource-facing service candidates during service order capture and to retrieve service candidates belonging to a given category. He gets all details on service candidates, service specifications and their characteristics (GET/serviceCandidate).

UC2: The provider wants to retrieve the characteristics of a given service candidate. (GET/serviceCandidate/: id [KM2] ).

UC3: The customer wants to retrieve the characteristics of a given customer-facing service candidate. (GET/serviceCandidate/: id [KM3] ).

RESOURCE MODEL

Managed Entity and Task Resource Models

Service Lifecycle Management:

Service Lifecycle Management (SLM) is responsible for managing the entire lifecycle of the catalog element and its underlying components. This includes all of the processes required to design, build, deploy, maintain and ultimately retire the catalog element.

When the macro conception of a catalog element is started the first status of the later is “In Study”.

When the conception of the catalog element is accepted its status is changed to “In Design”.

If the design is approved its status is changed to “In Test”.

Then either the test is OK and then its status is changed to “Active” or the test is KO and its status is changed to “Rejected”. The Rejected status is a final status.

When a catalog element is in a “Active” status it means it has been validated and tested, but it is still not available for customers.

When the beginning of marketing is reached, its status is changed to “Launched”. At this moment customers can buy it.

If the catalog element is not launched, its status is changed to “Retired”.

The same status is achieved when a catalog element reaches the end of marketing.

The “Retired” status means it cannot be sold to any new customers, but previous customers can still have it.

When no more customers hold the catalog element, its status is changed to “Obsolete” meaning it can be removed from the catalog.

 

Service Catalog

The root entity for service catalog management.

A service catalog is a group of ServiceSpecifications made available through ServiceCandidates that an organization provides to the consumers (internal consumers like its employees or B2B customers or B2C customers). A service catalog typically includes name, description and time period that is valid for. It will have a list of ServiceCandidates. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.

 

A ServiceCandidate and its associated ServiceSpecification may be “published” – made visible – in any number of ServiceCatalogs, or in none.  One ServiceSpecification can be composed of other ServiceSpecifications.  These ServiceSpecifications may also be published.

 

Below is a representation of the Service Catalog resource in JSON format.

 

{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"type" : "ServiceCatalog" ,
"category [KM4] " : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,

"name" : "Catalog Wholesale Business" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-07-23T16:42:23-04:00" ,
"endDateTime" : "2017-07-23T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

 

 

Field Descriptions :

Field

Description

category

Reference to the category

href

Hyperlink reference to the catalog

id

Unique identifier of the catalog

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the catalog

type

Indicates the type of catalog. For service catalogs, this will always be ‘ServiceCatalog’.

validFor

The period for which the catalog is valid

version

Catalog version

 

RelatedParty : Defines party or partyRole linked to a specific entity.

Field

Description

id

Unique identifier of related party

href

Hyperlink reference to the relatedParty, could be a party reference or a partyRole reference

name

Name of the related party

role

Role of the related party

validFor

The period for which the related party is linked to the entity

 

UML model:

 

Category [KM5]

The category resource is used to group service candidates in logical containers.

Categories can contain other categories and/or service candidates.

Resource IDs for categories are strings and are defined by the catalog application.

Below is a representation of the Category resource in JSON format.

{
"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"
}

Or for a root category (e.g. no parent)

{
"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" : "" ,
"isRoot" : true ,
"name" : "Cloud Services" ,
"description" : "A category to hold all available cloud services"
}

 

Field Descriptions :

Category : 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.

Field

Description

description

Description of the category

href

Hyperlink reference to the catalog

id

Unique identifier of the category

isRoot

If true, this Boolean indicates that the category is a root of categories

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the category

parentId

Unique identifier of the parent category

validFor

The period for which the category is valid

version

Category version

 

 

UML model:

 

Service Candidate

A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog. A ServiceCandidate and its associated ServiceSpecification may be published - made visible - in any number of ServiceCatalogs, or in none. One ServiceSpecification can be composed of other ServiceSpecifications. The Service Candidate consists of a subset of ServiceSpecification characteristics to fulfill a product offering. These ServiceSpecifications may also be published.

The Service Candidate resource (JSON format) represents a set of characteristics that define the values given by the ServiceSpecification.

Resource IDs are numeric and generated by the Catalog application.

Below is a representation of the ServiceCandidate resource in JSON format.

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"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/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
[KM6] "serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

UML model:

 

Service Specification

ServiceSpecification is a class that offers characteristics to describe a type of service.

Functionally, it acts as a template by which Services may be instantiated. By sharing the same specification, these services would therefore share the same set of characteristics.

Note: The ‘configurable’ attribute on the serviceSpecCharacteristics determines if a Service instantiated from the serviceSpecification can override the value of the attribute. When set to false, the service instance may not define a value that differs from the value in the specification.

Below is a representation of the ServiceSpecification resource in JSON format.

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/22" ,
"version" : "2. 0 [KM7] " ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"name" : "Virtual Storage Medium" ,

            "type" : "CustomerFacingService" ,
"description" : "Virtual storage via the cloud." ,

"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"attachment" : [] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"serviceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : " http://serverlocation:port/catalogManagement/serviceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"requiredResourceSpecification" : [
{
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"serviceSpecCharacteristic" : [
{
"name" : " Size" ,
"description" : " size" ,
"valueType" : "number" ,
"configurable" : true ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"serviceSpecCharRelationship" : [] ,
"serviceSpecCharacteristicValue" : [

{
"valueType" : "number" ,
"default" : true ,
"value" : "500" ,
"unitOfMeasure" : "MB" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
},
{
"valueType" : "number" ,
"default" : false ,
"value" : "10" ,
"unitOfMeasure" : "GB" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
},

{
"valueType" : "number" ,
"default" : false ,
"value" : "50" ,
"unitOfMeasure" : "GB" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
},
]
}
]
}

 

Field Descriptions :

Attachment : describes a service through video, pictures...

Field

Description

description

Description of the attachment

href

Hyperlink reference to the attachment

id

Unique identifier of the attachment

type

Attachment type such as video, picture

uri

Uniform Resource Identifier, describes the mechanism used to access the resource, the specific computer that the resource is housed in, the specific name of the resource (file name) on the computer

url

Uniform Resource Locator, is a web page address (a subset of URI)

 

 

Catalog : A service catalog is a group of ServiceSpecifications made available through ServiceCandidates that an organization provides to the consumers (internal consumers like its employees or B2B customers or B2C customers). A service catalog typically includes name, description and time period that it is valid for. It will have a list of ServiceCandidates. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.

 

 

Field

Description

category

Reference to the category

href

Hyperlink reference to the catalog

id

Unique identifier of the catalog

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the catalog

type

Indicates if the catalog is a product, service or resource catalog

validFor

The period for which the catalog is valid

version

Catalog version

 

Category : The category resource is used to group service candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.

Field

Description

description

Description of the category

href

Hyperlink reference to the catalog

id

Unique identifier of the category

isRoot

If true, this Boolean indicates that the category is a root of categories

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the category

parentId

Unique identifier of the parent category

validFor

The period for which the category is valid

version

Category version

 

 

ServiceSpecCharacteristic : A characteristic quality or distinctive feature of a ServiceSpecification.  The characteristic can be take on a discrete value, such as color, can take on a range of values, (for example, sensitivity of 100-240 mV), or can be derived from a formula (for example, usage time (hrs) = 30 – talk time *3).  Certain characteristics, such as color, may be configured during the ordering or some other process.

Field

Description

configurable

If true, the Boolean indicates that the serviceSpecCharacteristic is configurable

description

A narrative that explains in detail what the serviceSpecCharacteristic is

href

Hyperlink reference to the serviceSpecCharacteristic

id

Unique identifier of the serviceSpecCharacteristic

name

Name of the serviceSpecCharacteristic

valueType

A kind of value that the characteristic can take on, such as numeric, text and so forth

validFor

The period for which the serviceSpecCharacteristic is valid

 

ServiceSpecCharRelationship : An aggregation, migration, substitution, dependency or exclusivity relationship between/among serviceSpecCharacteristics.

Field

Description

href

Hyperlink reference to the serviceSpecCharacteristic

validFor

The period for which the relationship is valid

type

Type of relationship such as aggregation, migration, substitution, dependency, exclusivity

 

ServiceSpecCharacteristicValue : A number or text that can be assigned to a ServiceSpecCharacteristic.

Field

Description

default

Indicates if the value is the default value for a characteristic

unitOfMeasure

Could be minutes, GB, etc

validFor

The period of time for which a value is applicable

value

A discrete value that the characteristic can take on

valueFrom

The low range value that a characteristic can take on

valueTo

The upper range value that a characteristic can take on

valueType

A kind of value that the characteristic can take on, such as numeric, text, and so forth

 

ServiceSpecificationRelationship : A migration, substitution, dependency or exclusivity relationship between/among service [KM8] specifications.

Field

Description

id

Identifier for the serviceSpecification

href

Hyperlink reference to the serviceSpecification

validFor

The period for which the serviceSpecificationRelationship is valid

Type

Type of relationship such as migration, substitution, dependency, exclusivity

 

RelatedParty : Defines party or partyRole linked to a specific entity.

Field

Description

id

Identifier for the related party or partyRole

href

Hyperlink reference to the relatedParty, could be a party reference or a partyRole reference

name

Name of the related party

role

Role of the related party

validFor

The period for which the related party is linked to the entity

 

RequiredResourceSpecification: Refers to the ResourceSpecifications required to realize a ServiceSpecification.

Field

Description

id

Identifier for the RequiredResourceSpecification

href

Hyperlink reference to the RequiredResourceSpecification

name

Name of the RequiredResourceSpecification

validFor

The period for which the RequiredResourceSpecification is valid

 

RequiredServiceSpecification: Refers to the ServiceSpecifications required to realize a ServiceSpecification.

Field

Description

id

Identifier for the RequiredServiceSpecification

href

Hyperlink reference to the RequiredServiceSpecification

name

Name of the RequiredServiceSpecification

validFor

The period for which the RequiredServiceSpecification is valid

 

ServiceSpecCharacteristic: This class represents the key features of this ServiceSpecification. For example, bandwidth is a characteristic of many different types of services; if bandwidth is a relevant characteristic (e.g., from the point-of-view of a Customer obtaining this Service via a Product) then bandwidth would be a ServiceCharacteristic for that particular Service.

 

Field

Description

configurable

If true, the Boolean indicates that the serviceSpecCharacteristic is configurable

description

A narrative that explains in detail what the serviceSpecCharacteristic is

href

Hyperlink reference to the serviceSpecCharacteristic

id

Unique identifier of the serviceSpecCharacteristic

name

Name of the serviceSpecCharacteristic

valueType

A kind of value that the characteristic can take on, such as numeric, text and so forth

validFor

The period for which the serviceSpecCharacteristic is valid

 

UML model:

 

 

 

 

 

 

 

Figure 1 - ServiceSpecification resource model

 

 

Notification Resource Models

Two notification event types are defined:

  1. CatalogChangeNotification
  2. CatalogChangeBatchNotification

Catalog Notification UML Diagram:

Catalog change notification: notifies that a catalog has been updated.

{
"event" : {
"id" : "01" ,
"dateTime" : "2013-04-19T16:42:25-30:00" ,
"eventType" : "Catalog change notification" ,
"catalog" : [
{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/catalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"type" : "ServiceCatalog" ,
"name" : "Catalog Wholesale Business"
}
]
}
}

 

Catalog change batch notification: notifies in detail all catalog updates.

{    
      "event" :{    
            "id" :"01",
            "dateTime" :"2013-04-19T16:42:25-30:00",
            "eventType" :"Catalog   change   batch   notification",
            "catalog" :[    
                  {    
                        "id" :"10",
                        "href" :"http://serverlocation:port/catalogManagement/catalog/10",
                        "version" :"2.0",
                        "lastUpdate" :"2013-04-19T16:42:23-04:00",
                        "type" :"ServiceCatalog",
                        "name" :"Catalog   Wholesale   Business",
                        "update" :[    
                              {    
                                    "op" :"add",
                                    "path" :"/category",
                                    "value" :{    
                                          "id" :"45",
                                          "href" :"http://serverlocation:port/catalogManagement/category/45",
                                          "lastUpdate" :"2016-08-12T16:42:23-04:00",
                                          "version" :"1.0",
                                          "lifecycleStatus" :"Active",
                                          "validFor" :{    
                                                "startDateTime" :"2016-08-12:42:23-04:00",
                                                "endDateTime" :""
                                          },
                                          "parentId" :"41",
                                          "isRoot" :true,
                                          "name" :"Residential   Fibre   Services",
                                          "description" :"A   category   to   hold   all   available   residential   fibre   offers"
                                    }
                              },
                              {    
                                    "op" :"add",
                                    "path" :"/category",
                                    "value" :{    
                                          "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   "
                                    }
                              },
                              {    
                                    "op" :"add",
                                    "path" :"/serviceSpecification",
                                    "value" :{    
                                          "id" :"36",
                                          "href" :"http://serverlocation:port/catalogManagement/serviceSpecification/36",
                                          "version" :"1.0",
                                          "lastUpdate" :"2016-08-12T16:42:23-04:00",
                                          "name" :"Residential   Fibre",
                                          "description" :"A   residential   fibre   service",
                                          "lifecycleStatus" :"Active",
                                          "validFor" :{    
                                                "startDateTime" :"2013-04-19T16:42:23-04:00",
                                                "endDateTime" :"2013-06-19T00:00:00-04:00"
                                          },
                                          "relatedParty" :[    
                                                {    
                                                      "role" :"Owner",
                                                      "id" :"1234",
                                                      "href" :"http   ://serverLocation:port/partyManagement/partyRole/1234"
                                                }
                                          ],
                                          "serviceSpecCharacteristic" :[    
                                                {    
                                                      "name" :"Connection   Number",
                                                      "description" :"Connection   Number",
                                                      "valueType" :"number",
                                                      "configurable" :true,
                                                      "validFor" :{    
                                                            "startDateTime" :"2016-08-12T16:42:23-04:00",
                                                            "endDateTime" :""
                                                      },
                                                      "serviceSpecCharacteristicValue" :[    
                                                            {    
                                                                  "valueType" :"string",
                                                                  "default" :false,
                                                                  "value" :"",
                                                                  "unitOfMeasure" :"",
                                                                  "valueFrom" :"",
                                                                  "valueTo" :"",
                                                                  "validFor" :{    
                                                                        "startDateTime" :"2016-08-12T16:42:23-04:00",
                                                                        "endDateTime" :""
                                                                  }
                                                            }
                                                      ]
                                                }
                                          ]
                                    }
                              }
                        ]
                  }
            ]
      }
}

 

 

Export and Import Job Notifications

  1. Export Job Completion Notification
  2. Import Job Completion Notification

UML Model:

 

Event: ExportJobCompletionNotification

 

{
    "eventType" : "ExportJobCompletionNotification" ,
    "eventTime" : "2014-09-27T05:46:25.0Z" ,
    "eventId" : "1154278" ,
    "event" : { "exportJob" : {
        "id" : "54" ,
        "href" : "http:/api/catalogManagement/exportJob/54" ,
        "status" : "succeeded" ,
        "path" : "catalogManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.mycatalog.com/catalogManagement/54.json"
    }}
}

 

 

 

Event: ImportJobCompletionNotification

 

{
    "eventType" : "ImportJobCompletionNotification" ,
    "eventTime" : "2014-09-27T05:46:25.0Z" ,
    "eventId" : "1154278" ,
    "event" : { "importJob" : {
        "id" : "54" ,
        "href" : "http:/api/catalogManagement/importJob/54" ,
        "status" : "succeeded" ,
        "path" : "catalogManagement/" ,
        "content-type" : "application/json" ,
        "errorLog" : "" ,
        "creationDate" : "2013-04-19T16:42:23-04:00" ,
        "completionDate" : "2013-04-21T16:42:23-04:00" ,
        "url" : "ftp://ftp.mycatalog.com/catalogManagement/54.json"
    }}
}

 

API OPERATION TEMPLATES

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/serviceCatalog/{ID}

This Uniform Contract operation is used to retrieve the representation of the service catalog managed entity or collection.

Note that the SERVICECATALOG collection can be retrieved via GET /api/SERVICECATALOG with no {ID}

Description :

  • This operation returns service catalogs.
  • The resource instance being returned is a ServiceCatalog or an array of ServiceCatalogs 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 serviceCandidate found
    • 404 Not found when the supplied ID doesn’t match a known ServiceCandidate.
  • Filtering is enabled on all ServiceCandidate attributes.
  • Attribute selection is enabled.

REQUEST

GET /catalogManagement/serviceCatalog/{10}

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

{ [KM9]
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"type" : "ServiceCatalog" ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,

"name" : "Catalog Wholesale Business" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-07-23T16:42:23-04:00" ,
"endDateTime" : "2017-07-23T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

 

 

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 serviceCategory [KM10] 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 serviceCategory [KM11] , 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/{12}

Accept: application/json

RESPONSE

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/serviceCandidate/{ID}

This Uniform Contract operation is used to retrieve the representation of the serviceCandidate managed entity or collection.

Note that the SERVICECANDIDATE collection can be retrieved via GET /api/serviceCandidate with no {ID}

Description :

  • This operation returns ServiceCandidates. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.
  • The resource instance being returned is a ServiceCandidate or an array of ServiceCandidates 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 serviceCandidate found
    • 404 Not found when the supplied ID doesn’t match a known ServiceCandidate.
  • Filtering is enabled on all ServiceCandidate attributes.
  • Attribute selection is enabled.

REQUEST

GET /catalogManagement/serviceCandidate/{42}

Accept: application/json

RESPONSE [KM12]

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : " 42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud service"
}
] ,
"serviceLevelAgreement" : {
"id" : " 28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
[KM13] "serviceSpecification" : {
"id" : " 13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

GET /catalogManagement/serviceSpecification/{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/serviceSpecification with no {ID}

Description :

  • This operation returns ServiceSpecifications.
  • The resource instance being returned is a ServiceSpecification or an array of ServiceSpecifications 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 ServiceSpecification found when retrieving a collection.
    • 404 Not found when the supplied ID doesn’t match a known ServiceSpecification.
  • Filtering is enabled on all ServiceSpecification attributes.
  • Attribute selection is enabled.

REQUEST

GET /catalogManagement/serviceSpecification/{22}

Accept: application/json

RESPONSE [KM14]

200

Content-Type: application/json

 

{    
        "id" : "22",
        "href" : "http://serverlocation:port/catalogManagement/serviceSpecification/22",
        "version" : "3.0",
        "lastUpdate" : "2013-04-19T16:42:23-04:00",
        "lifecycleStatus" : "Active",
        "name" : "Virtual   Storage   Medium",

    "type" : "CustomerFacingService",
        "description" :" Virtual   storage   via   the   cloud.",
        "validFor" : {    
                "startDateTime" : "2013-04-19T16:42:23-04:00",
                "endDateTime" : "2013-06-19T00:00:00-04:00"
        },
        "attachment" : [],
        "relatedParty" : [    
                {    
                        "role" : "Owner",
                        "id" : "1234",
                        "href" : "http   ://serverLocation:port/partyManagement/partyRole/1234"
                }
        ],
        "serviceSpecRelationship" : [    
                {    
                        "type" :"dependency ",
                        "id" : "23",
                        "href" : "http://serverlocation:port/catalogManagement/serviceSpecification/23",
                        "validFor" : {    
                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                "endDateTime" : ""
                        }
                }
        ],
        "requiredServiceSpecification" : [    
                {    
                        "id" : "13",
                        "href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13",
                        "name" : "specification   1",
                        "validFor" : {    
                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                "endDateTime" : ""
                        }
                }
        ],
        "requiredResourceSpecification" : [    
                {    
                        "id" : "13",
                        "href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13",
                        "name" : "specification   1",
                        "validFor" : {    
                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                "endDateTime" : ""
                        }
                }
        ],
        "serviceSpecCharacteristic" : [    
                {    
                        "name" : "Size",
                        "description" : "size",
                        "valueType" : "number",
                        "configurable" : true,
                        "validFor" : {    
                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                "endDateTime" : ""
                        },
                        "serviceSpecCharRelationship" : [],
                        "serviceSpecCharacteristicValue" : [    
                                {    
                                        "valueType" : "number",
                                        "default" : true,
                                        "value" : "500",
                                        "unitOfMeasure" : "MB",
                                        "valueFrom" : "",
                                        "valueTo" : "",
                                        "validFor" : {    
                                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                                "endDateTime" : ""
                                        }
                                },
                                {    
                                        "valueType" : "number",
                                        "default" : false,
                                        "value" :"10",
                                        "unitOfMeasure" : "GB",
                                        "valueFrom" : "",
                                        "valueTo" : "",
                                        "validFor" : {    
                                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                                "endDateTime" : ""
                                        }
                                },
                                {    
                                        "valueType" : "number",
                                        "default" : false,
                                        "value" : "50",
                                        "unitOfMeasure" : "GB",
                                        "valueFrom" : "",
                                        "valueTo" : "",
                                        "validFor" : {    
                                                "startDateTime" : "2013-04-19T16:42:23-04:00",
                                                "endDateTime" : ""
                                        }
                                }
                        ]
                }
        ]
}

 

 

GET /catalogManagement/exportJob/{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 the status of an exportJob.
  • 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 ExportJob found
    • 404 Not found when the supplied ID doesn’t match a known ExportJob.
  • Filtering is enabled on all ExportJob attributes.
  • Attribute selection is enabled.

GET /catalogManagement/exportJob/{10}

Accept: application/json

RESPONSE [KM15]

200

Content-Type: application/json

 

{
"id" : "10" ,
"status" : "Succeeded"

}
 

 

GET /catalogManagement/importJob/{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 the status of an importJob.
  • 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 ImportJob found
    • 404 Not found when the supplied ID doesn’t match a known ImportJob.
  • Filtering is enabled on all ImportJob attributes.
  • Attribute selection is enabled.

GET /catalogManagement/importJob/{25}

Accept: application/json

RESPONSE [KM16]

200

Content-Type: application/json

 

{
"id" : "25" ,
"status" : "Succeeded"

}
 

 

GET/…depth

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 :

  • The depth parameter allows retrieval of the resource at different levels of depth. The resource properties are provided and the related resources are returned according to the depth value.
  • 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 resources are found
    • 404 Not found when the supplied ID doesn’t match a known resource.
  • Filtering is enabled on all ServiceCandidate attributes.
  • Attribute selection is enabled.
  • This operation can return a very large amount of data. The Content-Range header must be used to control the amount of data returned. The header is present in the request and controls the minimum and maximum values returned. In the response, the content-Range header is used to indicate the presence of more elements in the collection and the current position of the elements in the overall collection.

 

GET /catalogManagement/serviceCandidate?depth=3&place.name=France&category.name=Wireless sensors

Range:items=23-24

Accept: application/json

RESPONSE

200

Content-Type: application/json

Content [KM17] -Range:items 23-24/50

 

[

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
"serviceSpecification" : {

"id": "22",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/22",

"version": "3.0",

"lastUpdate": "2013-04-19T16:42:23-04:00",

"lifecycleStatus": "Active",

"name": "Virtual Storage Medium",

                        "type" : "CustomerFacingService",

"description":" Virtual storage via the cloud.",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": "2013-06-19T00:00:00-04:00"

},

"attachment": [],

"relatedParty": [ 

"role": "Owner",

"id": "1234",

"href": "http ://serverLocation:port/partyManagement/partyRole/1234"

}

],

"serviceSpecRelationship": [ 

"type":"dependency ",

"id": "23",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/23",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredServiceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredResourceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/resourceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"serviceSpecCharacteristic": [ 

"name": "Size",

"description": "size",

"valueType": "number",

"configurable": true,

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

},

"serviceSpecCharRelationship": [],

"serviceSpecCharacteristicValue": [ 

"valueType": "number",

"default": true,

"value": "500",

"unitOfMeasure": "MB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value":"10",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value": "50",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

]

}

]

}

     }

]

PUT /catalogManagement/serviceCatalog/{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 catalog.
  • 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/serviceCatalog /10

Content-type: application/json

 

{
"version" : "2.0" ,
"type" : "ServiceCatalog" ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,

"name" : "Catalog Wholesale Business" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-07-23T16:42:23-04:00" ,
"endDateTime" : "2017-07-23T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "2800" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/2800"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

RESPONSE

 

200

Content-Type: application/json

 

{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2016-07-23T16:42:23-04:00" ,
"type" : "ServiceCatalog" ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,

"name" : "Catalog Wholesale Business" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-07-23T16:42:23-04:00" ,
"endDateTime" : "2017-07-23T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "2800" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/2800"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

 

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" : "2018-04-19T16:42:23-04:00"
} ,
"parentId" : " 41" ,
"isRoot" : false ,
"name" : "Cloud Services" ,
"description" : "A category to hold all available cloud service offers"
}

 

RESPONSE

200

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" : "2018-04-19T16:42:23-04:00"
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Services" ,
"description" : "A category to hold all available cloud service offers"
}

 

 

PUT /catalogManagement/serviceCandidate/{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 service candidate.
  • 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/serviceCandidate {42}

Content-type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2013-06-19T00:00:00-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services "
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
"serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-06-19T00:00:00-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2013-06-19T00:00:00-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
"serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

PUT /catalogManagement/serviceSpecification/{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 service specification.
  • 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/serviceSpecification /22

Content-type: application/json

 

"id": "22",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/22",

"version": "3.0",

"lastUpdate": "2016-08-14T16:42:23-04:00",

"lifecycleStatus": "Active",

"name": "Virtual Storage Medium",

            "type" : "CustomerFacingService",

"description":" Virtual storage via the cloud.",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": "2013-06-19T00:00:00-04:00"

},

"attachment": [],

"relatedParty": [ 

"role": "Owner",

"id": "1234",

"href": "http ://serverLocation:port/partyManagement/partyRole/1234"

}

],

"serviceSpecRelationship": [ 

"type":"dependency ",

"id": "23",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/23",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredServiceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredResourceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/resourceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"serviceSpecCharacteristic": [ 

"name": "Size",

"description": "size",

"valueType": "number",

"configurable": true,

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

},

"serviceSpecCharRelationship": [],

"serviceSpecCharacteristicValue": [ 

"valueType": "number",

"default": true,

"value": "10",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value":"20",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value": "50",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

]

}

]

1.1.1.1.1       }

RESPONSE

200

Content-Type: application/json

 

"id": "22",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/22",

"version": "3.0",

"lastUpdate": "2016-08-14T16:42:23-04:00",

"lifecycleStatus": "Active",

"name": "Virtual Storage Medium",

            "type" : "CustomerFacingService",

"description":" Virtual storage via the cloud.",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": "2013-06-19T00:00:00-04:00"

},

"attachment": [],

"relatedParty": [ 

"role": "Owner",

"id": "1234",

"href": "http ://serverLocation:port/partyManagement/partyRole/1234"

}

],

"serviceSpecRelationship": [ 

"type":"dependency ",

"id": "23",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/23",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredServiceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/serviceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"requiredResourceSpecification": [ 

"id": "13",

"href": "http://serverlocation:port/catalogManagement/resourceSpecification/13",

"name": "specification 1",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

],

"serviceSpecCharacteristic": [ 

"name": "Size",

"description": "size",

"valueType": "number",

"configurable": true,

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

},

"serviceSpecCharRelationship": [],

"serviceSpecCharacteristicValue": [ 

"valueType": "number",

"default": true,

"value": "10",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value":"20",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value": "50",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

]

}

]

}

PATCH /catalogManagement/serviceCatalog/{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 service catalog.
  • 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 200 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

type

Y

 

name

Y

 

description

Y

 

category

Y

 

relatedParty

Y

 

 

REQUEST

PATCH /catalogManagement/serviceCatalog /10

Content-type: application/json

 

{

"validFor" : {
"startDateTime" : "2017-07-23T00:00:00-00:00" ,
"endDateTime" : "2018-07-23T00:00:00-00:00"
}

}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2016-07-25T22:55:23-04:00" ,
"type" : "ServiceCatalog" ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,

"name" : "Catalog Wholesale Business" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2017-07-23T00:00:00-00:00" ,
"endDateTime" : "2018-07-23T00:00:00-00:00"
} ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "2800" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/2800"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

 

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.

When isRoot is patched to true, parentId should be empty.

 

REQUEST

PATCH /catalogManagement/category /42

Content-type: application/json

 

{

"parentId" : "" ,
"isRoot" : true
}

RESPONSE

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" : "" ,
"isRoot" : true ,
"name" : "Cloud Services" ,
"description" : "A category to hold all available cloud service offers"
}

 

 

PATCH /catalogManagement/serviceCandidate/{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 serviceCandidate.
  • 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

 

startDateTime

Y

 

endDateTime

Y

Should be greater than startDateTime

name

Y

 

version

Y

 

description

Y

 

lastUpdate

N

 

lifecycleStatus

Y

Status should be valid

category

Y

It should exist

serviceSpecification

Y

It should exist

 

             Further document any rules that must be implemented when patching attributes.

 

Rule name

Rule/Pre Condition/Side Effects/Post Conditons

 

 

 

REQUEST

PATCH /catalogManagement/serviceCandidate /{42}

Content-type: application/json

 

{

"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2013-06-20T00:00:01-04:00" ,
"endDateTime" : ""
}

}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-06-20T00:00:01-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2013-06-20T00:00:01-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
"serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

PATCH /catalogManagement/serviceSpecification/{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 serviceSpecification.
  • 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

name

Y

 

description

Y

 

brand

Y

 

relatedParty

Y

It should exist

attachment

Y

It should exist

serviceSpecRelationship

Y

It should exist

requiredServiceSpecification

Y

It should exist

requiredResourceSpecification

Y

It should exist

serviceSpecCharacteristic

Y

It should exist

serviceSpecCharRelationship

Y

It should exist

serviceSpecCharacteristicValue

Y

 

 

             Further document any rules that must be implemented when patching attributes.

 

Rule name

Rule/Pre Condition/Side Effects/Post Conditons

 

 

 

REQUEST

PATCH /catalogManagement/serviceSpecification /22

Content-type: application/json-patch+json

 

{
"op" : "add" ,
"path" : "/attachment" ,
"value" : {
"id" : "44" ,
"href" : "http://serverlocation:port/documentManagement/attachment/44" ,
"type" : "Video",
"url" : "http://yyyyy"
}
}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/22" ,
"version" : "2.0" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"name" : "Virtual Cloud" ,
"description" : "Virtual Cloud service" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"attachment" : [
{
"id" : "44" ,
"href" : "http://serverlocation:port/documentManagment/attachment/44" ,
"type" : "Video" ,
"url" : "http://yyyyy"
}
] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"serviceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : " http://serverlocation:port/catalogManagement/serviceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"requiredServiceSpecification" : [
{
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"requiredResourceSpecification" : [
{
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"serviceSpecCharacteristic": [ 

"name": "Size",

"description": "size",

"valueType": "number",

"configurable": true,

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

},

"serviceSpecCharRelationship": [],

"serviceSpecCharacteristicValue": [ 

"valueType": "number",

"default": true,

"value": "500",

"unitOfMeasure": "MB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value":"10",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

},

"valueType": "number",

"default": false,

"value": "50",

"unitOfMeasure": "GB",

"valueFrom": "",

"valueTo": "",

"validFor": { 

"startDateTime": "2013-04-19T16:42:23-04:00",

"endDateTime": ""

}

}

]

}

]

}

 

 

 

POST /catalogManagement/category/{ID}

 

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" : " 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-19T16:42:23-04:00" ,
"version" : "1.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"
}

 

 

POST /catalogManagement/serviceCandidate/{ID}

 

This Uniform Contract operation is used to create a managed entity or a task.

Description :

  • This operation creates a serviceCandidate.
  • 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 serviceCandidate id.

 

Specify the attributes required when an entity is created (and their default values if not):

Attribute name

Mandatory

Default

Rule

name

Y

 

 

serviceSpecification

Y

 

 

 

  • Further specify any rules on the creation of the entity

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/serviceCandidate

Content-type: application/json

 

{

"name" : "Virtual Storage Medium" ,
"version" : "1.0" ,
"description" : "Virtual Storage Medium" ,

"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/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
[KM18] "serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

RESPONSE

201

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/serviceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"version" : "1.0" ,
"description" : "Virtual Storage Medium" ,
"lastUpdate" : "2013-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"version" : "2.0" ,
"name" : "Cloud Services"
}
] ,
"serviceLevelAgreement" : {
"id" : "28" ,
"href" : "http://serverlocation:port/slaManagement/serviceLevelAgreement/28" ,
"name" : "Standard SLA"
} ,
"serviceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

POST /catalogManagement/serviceSpecification/{ID}

 

This Uniform Contract operation is used to create a managed entity or a task.

Description :

  • This operation creates a serviceSpecification.
  • 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 serviceSpecification id.

 

Specify the attributes required when an entity is created (and their default values if not):

Attribute name

Mandatory

Default

Rule

name

Y

 

 

serviceSpecCharacteristic

Y

 

 

serviceSpecCharacteristicValue

Y

 

 

 

  • Further specify any rules on the creation of the entity

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/serviceSpecification

Content-type: application/json

 

{
"version" : "3.0" ,
"name" : "Virtual Storage Medium" ,

            "type" : "CustomerFacingService",
"description" : "Virtual storage via the cloud." ,

            "validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : "2013-06-19T00:00:00-04:00"
} ,
"attachment" : [] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"serviceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : " http://serverlocation:port/catalogManagement/serviceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"requiredServiceSpecification" : [
{
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/serviceSpecification/13" ,
"name" : "specification 1" ,
"validFor" : {
"startDateTime" : "2013-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"requiredResourceSpecification" : [
{
"id" : "13" ,