Page tree

 

Resource Catalog Management API

 

Document Number:  <TBD>

Document Version:  <V16.5.0.1>

Date:  August 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

Introduction

SAMPLE USE CASES

Lifecycle management Use Case

RESOURCE MODEL

Managed Entity and Task Resource Models

Resource Catalog

Category

Resource Candidate

Resource Specification

Notification Resource Models

API OPERATION TEMPLATES

GET /catalogManagement/category

GET /catalogManagement/resourceCandidate/{ID}

GET /catalogManagement/resourceSpecification/{ID}

GET /catalogManagement/exportJob/{ID}

GET /catalogManagement/importJob/{ID}

GET/…depth

PUT /catalogManagement/category/{ID}

PUT /catalogManagement/resourceCandidate/{ID}

PUT /catalogManagement/resourceSpecification/{ID}

PATCH /catalogManagement/category/{ID}

PATCH /catalogManagement/resourceCandidate/{ID}

PATCH /catalogManagement/resourceSpecification/{ID}

POST /catalogManagement/category

POST /catalogManagement/resourceCandidate

POST /catalogManagement/resourceSpecification

POST /catalogManagement/catalog/{ID}/importJob

POST /catalogManagement/catalog/{ID}/exportJob

DELETE …/{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

 

Introduction

 

The Resource Catalog Management API REST specification allows the management of the entire lifecycle of the Resource Catalog elements, the consultation of resource catalog elements during several processes such as ordering process, campaign management, sales management.

SAMPLE USE CASES

 

 

Lifecycle management Use Case

The Resource Catalog Management API REST Specification allows the management of the entire lifecycle of the resource catalog elements.

UC1: A partner updates his catalog. He notifies his distributor the catalog change. The distributor requests a catalog export. Then, he retrieves the catalog at the provided URL.

UC2: A partner updates his catalog. He notifies all catalog changes in detail to his distributor. This one updates his catalog copy.

UC3: A catalog administrator wants to retrieve effective duration of a resource candidate based on resource candidate identifier or other search criteria (GET/resourceCandidate).

UC4: A catalog administrator wants to retrieve all resource candidates in resource catalog(GET/resourceCandidate).

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

RESOURCE MODEL

Managed Entity and Task Resource Models

Resource Lifecycle Management:

Resource Lifecycle Management is responsible for managing the entire lifecycle of the resource catalog element and its underlying components. This include 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 can not be sold to any new customers, but previous customers can still have it.

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

 

Resource Catalog

The root entity for resource catalog management.

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

 

{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"type" : "Resource Catalog" ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,

"name" : "Cloud Resource Catalog " ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Supplier" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
} , {
"role" : "Reviser" ,
"name" : "Roger Collins"
}
]
}

 

 

Field Descriptions :

ResourceCatalog : is a collection of Resource Specifications (Virtual, Logical or Physical), made available through ResourceCandidates that an organization will provide it to its internal or external consumers.

Field

Description

category

Reference to the resource category

href

Reference of the resource 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 resource catalog

type

Indicates the catalog is a resource catalog

validFor

The period for which the catalog is valid

version

Catalog version

relatedParty

Defines party or partyRole linked to the resource catalog

 

category : is reference to a category of resource candidates in logical containers.

Field

Description

href

Reference of the category. It can include specific version of the category

id

Unique identifier of the category

name

Name of the category

 

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

Field

Description

id

Unique identifier of related party

href

Reference of 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

The Category resource is used to group resource candidates in logical containers.

Categories can contain other categories and/or resource 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" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Network Logical Resources" ,
"description" : "A category to hold all available network logical resources"
}

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

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "" ,
"isRoot" : true ,
"name" : "Logical Resources" ,
"description" : "A category to hold all available logical resources"
}

 

Field Descriptions :

Category : is used to group resource candidates in logical containers. Resource categories can contain other categories and/or resource candidates.

Field

Description

description

Description of the category

href

Reference of 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:

 

Resource Candidate

A ResourceCandidate is an entity that makes a ResourceSpecification available to a resource catalog.

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

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"                       
}
}

 

Field Descriptions :

ResourceCandidate : Is an entity that makes a ResourceSpecification available to a resource catalog. A ResourceCandidate and its associated ResourceSpecification may be published - made visible - in any number of ResourceCatalogs, or in none.

Field

Description

description

A narrative that explains in detail what the resource candidate is

href

Reference of the resource candidate

id

Unique identifier of the resource candidate

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the resource candidate

validFor

The period for which the resource candidate is valid

version

Resource candidate version

 

resourceSpecification : a reference to associated ResourceSpecification.

Field

Description

href

Reference of the resourceSpecification. It can include a specific version of the resourceSpecification.

id

Unique identifier for the requiredResourceSpecification

name

Name of the requiredResourceSpecification

 

Resource Specification

Description:

 

Resources are physical or non-physical components (or some combination of these) within an enterprise's infrastructure or inventory. They are typically consumed or used by Services (for example a physical port assigned to a service) or   contribute to   the realization of a Product (for example, a SIM card). They can be drawn from the Application, Computing and Network domains, and include, for example, Network Elements, software, IT systems, content and information, and technology components.

A ResourceSpecification is an abstract base class for representing a generic means for implementing a particular type of Resource. In essence, a ResourceSpecification defines the common attributes and relationships of a set of related Resources, while Resource defines a specific instance that is based on a particular ResourceSpecification.

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

 

{

"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/22" ,
             "name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"version" : "1.0" ,

"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,

            "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,

"name" : "devicePicture" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Supplier" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecificationRelationship" : [
{
"type" : "dependency" ,
"id" : "25" ,

                                    "name" : "battery" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/25"                            
] ,
"resourceSpecCharacteristic" : [
{
"id : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number " ,
"configurable" : false ,                                   

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,                                   

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : "true" ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "regex" : "[a-zA-Z]{3,12}$" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : false ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "rangeInterval" : "closed" ,                                                           

                                                            "regex" : "[a-zA-Z]{3,12}$" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

 

Field Descriptions :

ResourceSpecification : A ResourceSpecification is an abstract base class for representing a generic means for implementing a particular type of Resource. In essence, a ResourceSpecification defines the common attributes and relationships of a set of related Resources, while Resource defines a specific instance that is based on a particular ResourceSpecification.

Field

Description

description

A narrative that explains in detail what the resource specification is

href

Reference of the resource specification

id

Unique identifier of the resource specification

lastUpdate

Date and time of the last update

lifecycleStatus

Used to indicate the current lifecycle status

name

Name of the resource specification

validFor

The period for which the resource specification is valid

version

Resource specification version

type

Resource specification type

isComposite

A flag indicates if this resource specification is composite or not

 

 

resourceSpecCharacteristic: D efines the characteristic features of a ResourceSpecification. Every ResourceSpecification has a variety of important attributes, methods, constraints, and relationships, which distinguish that ResourceSpecification from other ResourceSpecifications.

Field

Description

configurable

If true, the Boolean indicates that the resourceSpecCharacteristic is configurable

description

A narrative that explains in detail what the resourceSpecCharacteristic is

href

Reference of the resourceSpecCharacteristic

id

Unique identifier of the resourceSpecCharacteristic

name

Name of the resourceSpecCharacteristic

valueType

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

validFor

The period for which the resourceSpecCharacteristic is valid

minCardinality

Minimum cardinality of this characteristic

maxCardinality

Maximum cardinality of this characteristic

extensible

A flag indicates that if this characteristic values can be by adding new values when instantiating a characteristic for an Entity.

 

resourceSpecCharacteristicValue: D efines the characteristic features of a Resource. Every Resource has a variety of important attributes and relationships, which distinguish that Resource from other Resources.

 

Field

Description

default

Indicates if the value is the default value for a characteristic

unitOfMeasure

Could be minutes, GB…

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

regex

A regular expression constraint for given value

rangeInterval

An indicator that specifies the inclusion or exclusion of the valueFrom and valueTo attributes.
if specified, possible values are "open", "closed", "closedBottom" and "closedTop".

 

attachment : describes a resource through document, video, pictures...

Field

Description

name

name of the attachment

href

Reference of the attachment

id

Unique identifier of the attachment

type

Attachment type such as video, picture

url

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

 

resourceSpecificationRelationship : reference to related resource specification.

Field

Description

name

Given name to the target resource specification

href

Reference of the resourcespecification

id

Unique identifier of the target resource specification

type

Relationship type to target resource specification

 

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

Field

Description

id

Unique identifier of related party

href

Reference of 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:

 

Figure 1 – Catalog resource model

 

Figure 2 – Category resource model

 

 

 

 

 

 

Figure 8 – ResourceCandidate resource model

Figure 9 – ResourceSpecification resource model

 

Notification Resource Models

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

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

 

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

{
"event" : {
"id" : "01" ,
"dateTime" : "2016-04-19T16:42:25-30:00" ,
"eventType" : "Catalog change batch notification" ,
"catalog" : [
{
"id" : "10" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCatalog/10" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"type" : "Resource Catalog" ,
"name" : "Cloud Resource Catalog" ,
"update" : [
{
"op" : "add" ,
"path" : "/category" ,
"value" : {
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "" ,
"isRoot" : true ,
"name" : "Cloud rsources" ,
"description" : "A category to hold all inside resources"
}
} , {
"op" : "add" ,
"path" : "/category" ,
"value" : {
"id" : "421" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCatalog/421" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "42" ,
"isRoot" : false ,
"name" : "Wireless sensors" ,
"description" : "A category to hold all wireless sensor resource candidates"
}
} , {
"op" : "add" ,
"path" : "/resourceSpecification" ,
"value" : {
"id" : "14" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/14" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Sensor" ,
"description" : "A wireless sensor" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"relatedParty" : [
{
"role" : "Supplier" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecCharacteristic" : [
{
"id" : "34" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : "false" ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}
} ,   {
"op" : "add" ,
"path" : "/resourceCandidate" ,
"value" : {
"id" : "4211" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/4211" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Sensor" ,
"description" : "A wireless sensor" ,                                                                                 "lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "421" ,
"href" : "http://serverlocation:port/catalogManagement/category/421" ,                                                                                                                                                                                                     "name" : "Wireless sensors"
}
] ,
"resourceSpecification" : [
{
"id" : "14" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/14" ,                                                                                                                                                                                       "name" : "Sensor"
}
]                                                                                                  
}
}
]
}
]
}
}

 

 

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/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 Category from a catalog. The category resource is used to group resource candidates in logical containers. Categories can contain other categories and/or resource 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 resource Category, children of a resource Category 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/json

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resource candidates"
}

 

 

GET /catalogManagement/resourceCandidate/{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 resourceCandidates from a catalog. A ResourceCandidate is an entity that makes a ResourceSpecification available to a catalog.
  • The resource instance being returned is a ResourceCandidate or an array of ResourceCandidates 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 ResourceCandidate found
    • 404 Not found when the supplied ID doesn’t match a known ResourceCandidate.
  • Filtering is enabled on all ResourceCandidate attributes.
  • Attribute selection is enabled.

REQUEST

GET /catalogManagement/resourceCandidate/42

Accept: application/json

RESPONSE

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"
}
}

 

GET /catalogManagement/resourceSpecification/{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 resourceSpecifications from a catalog. This is an abstract base class that is used to define the invariant characteristics and behavior (attributes, methods, constraints, and relationships) of a managed resource.
  • The resource instance being returned is a ResourceSpecification or an array of ResourceSpecifications 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 ResourceSpecification found
    • 404 Not found when the supplied ID doesn’t match a known ResourceSpecification.
  • Filtering is enabled on all ResourceSpecification attributes.
  • Attribute selection is enabled.

REQUEST

GET /catalogManagement/resourceSpecification/{22}

Accept: application/json

RESPONSE

200

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/22" ,
"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,

           "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Supplier" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,

"resourceSpecCharacteristic" : [
{
"id" : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id" : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                    "minCardinality" : 1 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : "false" ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-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

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

{
"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 to retrieve 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 resourceCandidate are found
    • 404 Not found when the supplied ID doesn’t match a known ImportJob.
  • Filtering is enabled on all resourceCandidate 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 control 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/resourceCandidate?depth=3&category.name=Wireless sensors

Range:items=23-24

Accept: application/json

RESPONSE

200

Content-Range:items 23-24/50

[
{
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/23" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Sensor mini" ,
"description" : "A wireless sensor for small garden" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "14" ,
"href" : "http://serverlocation:port/catalogManagement/category/14" ,
"version" : "2.0" ,
"name" : "Wireless sensors",

                                                "lastUpdate" : "2016-04-19T16:42:23-04:00" ,
                        "lifecycleStatus" : "Active" ,
                                    "validFor" : {
                              "startDateTime" : "2016-04-19T16:42:23-04:00" ,
                              "endDateTime" : ""
                                     } ,
                                    "parentId" : "" ,
                                   "isRoot" : true ,
                                    "description" : "A category to hold all wireless sensors"
}
] ,
"resourceSpecification" : [
{
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"version" : "2.0" ,
"name" : "wireless sensor mini" ,

"resourceSpecCharacteristic" : [
{
"id" : "34" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                                                         "minCardinality" : 0 ,

                                                                         "maxCardinality" : 1 ,

                                                                         "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : "false" ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : "false" ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}
]
} , {
"id" : "24" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/24" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Sensor maxi" ,
"description" : "A wireless sensor for big garden" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "14" ,
"href" : "http://serverlocation:port/catalogManagement/category/14" ,
"version" : "2.0" ,
"name" : "Wireless sensors"
}
] ,
"resourceSpecification" : [
{
"id" : "45" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/45" ,
"version" : "2.0" ,
"name" : "wireless sensor maxi" ,
"resourceSpecCharacteristic" : [
{
"id" : "34" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                                                         "minCardinality" : 0 ,

                                                                         "maxCardinality" : 1 ,

                                                                         "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : "false" ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : "false" ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-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 200 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" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resource candidates"
}

 

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"lastUpdate" : "2016-04-25T09:28:10-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resource candidates"
}

 

 

 

PUT /catalogManagement/resourceCandidate/{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 resource 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 200 if the request was successful.
  • Any other special return and/or exception codes.

REQUEST

PUT /catalogManagement/resourceCandidate/ 42

Content-type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"
}
}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"lastUpdate" : "2016-06-19T16:42:23-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"
}
}

 

PUT /catalogManagement/resourceSpecification/{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 resource 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/resourceSpecification/ 22

Content-type: application/json

 

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/22" ,
"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"brand" : "Apple" ,
"version" : "2.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,

            "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,


"resourceSpecCharacteristic" : [
{
"id" : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,

                                     "minCardinality" : 1 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id" : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : "false" ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/22" ,
"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"brand" : "Apple" ,
"version" : "2.0" ,
"lastUpdate" : "2016-06-19T16:42:23-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,

           "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "image/jpeg" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristic" : [
{
"id" : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,

                                    "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id" : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                    "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : false ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

 

Example see TMF REST Design Guidelines.

 

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 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

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" : "2016-04-19T16:42:23-04:00" ,
"version" : "2.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "" ,
"isRoot" : true ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resources"
}

 

 

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

 

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

resourceSpecification

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/resourceCandidate /42

Content-type: application/json

 

{

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

}

RESPONSE

200

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "2.0" ,
"lastUpdate" : "2016-06-20T00:00:01-04:00" ,
"lifecycleStatus" : "Launched" ,
"validFor" : {
"startDateTime" : "2016-06-20T00:00:01-04:00" ,
"endDateTime" : ""
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"version" : "2.0" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1" ,
"version" : "1.1"
}
}

 

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

name

Y

 

description

Y

 

brand

Y

 

relatedParty

Y

It should exist

attachment

Y

It should exist

resourceSpecRelationship

Y

It should exist

resourceSpecCharacteristic

Y

It should exist

resourceSpecCharRelationship

Y

It should exist

resourceSpecCharacteristicValue

Y

 

 

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

 

Rule name

Rule/Pre Condition/Side Effects/Post Conditons

 

 

 

REQUEST

PATCH /catalogManagement/resourceSpecification /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/resourceSpecification/22" ,
"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"brand" : "Apple" ,
"version" : "2.0" ,
"lastUpdate" : "2016-06-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,

            "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,
"url" : "http://xxxxx"
},
{
"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"
}
] ,
"resourceSpecRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristic" : [
{
"id" : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,

                                    "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id" : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,

                                    "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : false ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

 

Example see TMF REST Design Guidelines.

 

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" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resource candidates"
}

 

RESPONSE

201

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/category/42" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"version" : "1.0" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"parentId" : "41" ,
"isRoot" : false ,
"name" : "Cloud Resources" ,
"description" : "A category to hold all available cloud resource candidates"
}

 

 

 

POST /catalogManagement/resourceCandidate

 

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

Description:

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

 

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

Attribute name

Mandatory

Default

Rule

name

Y

 

 

resourceSpecification

Y

 

 

 

  • Further specify any rules on the creation of the entity

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/resourceCandidate

Content-type: application/json

 

{

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

           "lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"
}
}

RESPONSE

201

Content-Type: application/json

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"version" : "1.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,
"category" : [
{
"id" : "12" ,
"href" : "http://serverlocation:port/catalogManagement/category/12" ,
"name" : "Cloud resources"
}
] ,
"resourceSpecification" : {
"id" : "13" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/13" ,
"name" : "specification 1"
}
}

 

POST /catalogManagement/resourceSpecification

 

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

Description:

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

 

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

Attribute name

Mandatory

Default

Rule

name

Y

 

 

resourceSpecCharacteristic

Y

 

 

resourceSpecCharacteristicValue

Y

 

 

 

  • Further specify any rules on the creation of the entity

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/resourceSpecification

Content-type: application/json

 

{

"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"version" : "1.0" ,

"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,

            "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id" : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Supplier" ,
"id" : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecificationRelationship" : [
{
"type" : "dependency" ,
"id" : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristic" : [
{
"id : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,                                   

                                   "minCardinality" : 0 ,

                                   "maxCardinality" : 1 ,

                                   "extensible" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "regex" : "[a-zA-Z]{3,12}$" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : false ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,

                                                            "regex" : "[a-zA-Z]{3,12}$" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

RESPONSE

201

Content-Type: application/json

 

{
"id" : "22" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/22" ,
"name" : "iPhone 42" ,
"description" : "Siri works on this iPhone" ,
"brand": "Apple",
"version" : "1.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"lifecycleStatus" : "Active" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : "2016-06-19T00:00:00-04:00"
} ,

            "isComposite" : false ,

            "type" : "PhysicalResourceSpec" ,
"attachment" : [
{
"id : "22" ,
"href" : "http://serverlocation:port/documentManagment/attachment/22" ,
"type" : "Picture" ,
"url" : "http://xxxxx"
}
] ,
"relatedParty" : [
{
"role" : "Owner" ,
"id : "1234" ,
"href" : "http ://serverLocation:port/partyManagement/partyRole/1234"
}
] ,
"resourceSpecRelationship" : [
{
"type" : "dependency" ,
"id : "23" ,
"href" : "http://serverlocation:port/catalogManagement/resourceSpecification/23" ,                             "validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,

"resourceSpecCharacteristic" : [
{
"id" : "54" ,
"name" : "Screen Size" ,
"description" : "Screen size" ,
"valueType" : "number" ,
"configurable" : false ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharRelationship" : [
{
"type" : "dependency" ,
"id" : "43" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
] ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "number" ,
"default" : true ,
"value" : "4.2" ,
"unitOfMeasure" : "inches" ,
"valueFrom" : "" ,
"valueTo" : "" ,

            "rangeInterval" : "closed" ,

                                                            "regex" : "[-+]?[0-9]*\.?[0-9]+" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
} , {
"id" : "55" ,
"name" : "Colour" ,
"description" : "Colour" ,
"valueType" : "string" ,
"configurable" : true ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
} ,
"resourceSpecCharacteristicValue" : [
{
"valueType" : "string" ,
"default" : true ,
"value" : "Black" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
} , {
"valueType" : "string" ,
"default" : false ,
"value" : "White" ,
"unitOfMeasure" : "" ,
"valueFrom" : "" ,
"valueTo" : "" ,
"validFor" : {
"startDateTime" : "2016-04-19T16:42:23-04:00" ,
"endDateTime" : ""
}
}
]
}
]
}

 

POST /catalogManagement/catalog/{ID}/importJob

 

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

Description:

  • This operation manages a task to import a catalog.
  • 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 job id.

 

Specify the attributes required for the task (and their default values if not):

Attribute name

Mandatory

Default

Rule

url

Y

 

 

 

 

 

 

 

 

 

 

 

  • Further specify any rules for the task

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/catalog/10/importJob

Content-type: application/json

 

{

"url" : "ftp://ftp.myCatalog.com/resourceCatalog"

}

RESPONSE

201

Content-Type: application/json

 

{
"id" : "54" ,

"status" : "Succeeded" ,
"errorLog" : ""
}

 

POST /catalogManagement/catalog/{ID}/exportJob

 

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

Description:

  • This operation manages a task to export a catalog.
  • 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 job id.

 

Specify the attributes required for the task (and their default values if not):

Attribute name

Mandatory

Default

Rule

Catalog id

Y

 

 

 

 

 

 

 

 

 

 

 

  • Further specify any rules for the task

Rule name

Rule

 

 

 

REQUEST

POST catalogManagement/catalog/10/exportJob

Content-type: application/json

 

{

}

RESPONSE

201

Content-Type: application/json

 

{
"id" : "54" ,

"status" : "Succeeded" ,
"errorLog" : "" ,
"url" : "ftp://ftp.myCatalog.com/resourceCatalog"

}

 

 

Example see TMF REST Design Guidelines.

 

DELETE …/{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 204 if the request was successful.
  • Any other special return and/or exception codes.

REQUEST

DELETE /catalogManagement/resourceCandidate/42

 

 

RESPONSE

204

 

 

Example see TMF REST Design Guidelines.

 

 

 

 

API NOTIFICATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.

 

 

  REGISTER LISTENER POST /hub

Description:

Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not support multiple listeners. In this case, DELETE /api/hub/{id} must be called before an endpoint can be created again.

Behavior:

Returns HTTP/1.1 status code 201 if the request was successful.

 

Returns HTTP/1.1 status code 409 if request is not successful .

REQUEST

POST /api/hub

Accept: application/json

 

{ "callback" : "http://in.listener.com" }

RESPONSE

201

Content-Type: application/json

Location: /api/hub/42

 

{"id":"42","callback":"http://in.listener.com","query":null}

 

 

 

UNREGISTER LISTENER DELETE hub/{id}

Description:

Clears the communication endpoint address that was set by creating the Hub.

Behavior:

Returns HTTP/1.1 status code 204 if the request was successful.

 

Returns HTTP/1.1 status code 404 if the resource is not found.

REQUEST

DELETE /api/hub/{id}

Accept: application/json

 

RESPONSE

204

 

 

publish {EventTYPE} POST /listener

Description:

Provide the Event description

Behavior:

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

REQUEST

POST /client/listener

Accept: application/json

 

{
    "event" : {

    EVENT BODY
            } ,
    "eventType" : "eventType"
}

RESPONSE

201

Content-Type: application/json

 

 

Please see Notification Resource Models   or TMF REST Design Guidelines for more examples.

 

 

lifecycle management Extensions to Catalog

 

In Lifecycle Management there is a requirement to distinguish between entities existing with different life cycle version numbers and accessible via different ACL mechanisms.

For example, the same Resource Candidate may exist in a Catalog but with different version numbers.

It may be possible for an administrator to see all the existing versions or for a partner to see only a subset of all the existing versions.

The entity version number is not dependent on the version number of the API. For example, in PLM the same API (running at a specific version number) may be used to retrieve entities with different PLM version numbers.

In order to distinguish resources representing entities running with different version numbers and accessible though the same API version the following directive can be used /id:(version=x) and the version attribute is added to each entity.

 

 

{
"id" : "42" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/42" ,
"version" : "1.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Virtual Storage Medium" ,
"description" : "Virtual Storage Medium" ,
"lifecycleStatus" : "Active" ,

…..

}

 

Note that the catlog resources in this case may have the same ID but may be distinguished by the inclusion of the version number in their ID i.e /42:(version=1.0), /42:(version=2.0).

 

In the following examples we will assume that two versions of the VirtualStorage Service Candidate exist in the REsource Catalog. The Inactive and Active versions respectively version 1.0 and version 2.0.

 

Query all versioned catalog resources

Users with different roles may have access to different versions of the entities in the catalog.  For example user A may have access to only the version 1.0 of the entities while user B may have access to version 1.0 and version 2.0.

Admin user of Catalog have access to all the versions of the resources while non admin users have by default access to only the latest version of the entities in the Catalog. 

For example the following request on the admin endpoint will return all the versioned resources matching a specific ID.

REQUEST

GET api/admin/catalogManagement/resourceCandidate/?id=VirtualStorageMedium

Accept: application/json

RESPONSE

200

Content-Type: application/json

 

[

{
"id" : "VirtualStorageMedium" ,
"href" : "http://serverlocation:port/catalogManagement/resourceCandidate/VirtualStorage Medium" ,
"version" : "1.0" ,
"lastUpdate" : "2016-04-19T16:42:23-04:00" ,
"name" : "Virtual Storage Medium" ,
"description"<