Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


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 Product Offer exist in the Product 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/productOffering/?id=VirtualStorage
Accept: application/json

RESPONSE

200
Content-Type: application/json

[{
            "id": " VirtualStorage ",
            "href": "http://serverlocation:port/catalogManagement/productOffering/VirtualStorage",
            "version": "1.0",
            "lastUpdate": "2013-04-19T16:42:23-04:00",
            "name": "Virtual Storage Medium",
            "description": "Virtual Storage Medium",
            "isBundle": "true",
            "lifecycleStatus": "InActive",

…..

},

{
            "id": " VirtualStorage ",
            "href": "http://serverlocation:port/catalogManagement/productOffering/ VirtualStorage ",
            "version": "2.0",
            "lastUpdate": "2013-04-19T16:42:23-04:00",
            "name": "Virtual Storage Medium",
            "description": "Virtual Storage Medium",
            "isBundle": "true",
            "lifecycleStatus": "Active",

…..

}
]

...

Query a specific versioned CATALOG resource

In general a non admin API user only has visibility to the latest version number or visibility to a subset of versioned catalog resources.
It may be possible for an admin API user to retrieve a resource with a specific version number by using an ID and versioning filtering criteria.

REQUEST

GET api/admin/catalogManagement/productOffering/?id=VirtualStorage&version=1.0
Accept: application/json

RESPONSE

200
Content-Type: application/json

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

…..

]

...

...

Query current version of a catalog resource

By default only the most current version is returned (for admin and non admin).

REQUEST

GET api/admin/catalogManagement/productOffering/VirtualStorage
Accept: application/json

RESPONSE

200
Content-Type: application/json

{
            "id": "42",
            "href": "http://serverlocation:port/catalogManagement/productOffering/42",
            "version": "2.0",
            "lastUpdate": "2013-04-19T16:42:23-04:00",
            "name": "Virtual Storage Medium",
            "description": "Virtual Storage Medium",
            "isBundle": "true",
            "lifecycleStatus": "Active",

…..

}

...

Create new version of a CATALOG resource

POST is used to create a new version of a catalog resource.
The constraint is that the version numbers for the resource having the same ID must differ.

REQUEST

POST catalogManagement/productOffering
Content-type: application/json

{

      “id”: “VirtualStorage”,

            "version": "3.0",

            "name": "Virtual Storage Medium",
            "description": "Virtual Storage Medium",
            "isBundle": "true",
            "lifecycleStatus": "Active",
            "validFor": {
                        "startDateTime": "2013-04-19T16:42:23-04:00",
                        "endDateTime": "2013-06-19T00:00:00-04:00"
            },


            }

RESPONSE

201
Content-Type: application/json

{
            "id": "VirtualStorage",
            "href": "http://serverlocation:port/catalogManagement/productOffering/42",
            "version": "3.0",
            "lastUpdate": "2013-04-19T16:42:23-04:00",
            "name": "Virtual Storage Medium",
            "description": "Virtual Storage Medium",
            "isBundle": "true",
            "lifecycleStatus": "Active",
            "validFor": {
                        "startDateTime": "2013-04-19T16:42:23-04:00",
                        "endDateTime": "2013-06-19T00:00:00-04:00"
            },


            }

...

Modify an existing version of a CATalog resource

By default PATCH or PUT will be acting only on the latest version of a Catalog Resource. For example PATCH /…/productOffering/VirtualStorage will only update the VirtualStoage ProductOffering at Version 2.0 (which is the most current).
To update a specific version of an entity the (Version=X) directive is added to the ID (i.e /id:(version=x) .
Note that this capability is only available to API users having the proper authorizations to change the catalog entities with specific version numbers.
For example to change the VirtualStorage versioned at 1.0 we could use /productOffering/VirtualStorage(Version=1.0)

REQUEST

PATCH /catalogManagement/productOffering/VirtualStorage(Version=1.0)
Content-type: application/json-patch+json

{

"lifecycleStatus": "Active" }

RESPONSE

201
Content-Type: application/json

{
"id": "VirtualStorage",
"href": "http://serverlocation:port/catalogManagement/productOffering/VirtualStorage",
"version": "1.0",
"lifecycleStatus": "Active",
…..
}

 

...

Role based Access Control

The user presents their credentials for authentication
If the credentials are valid
1.The user is given access to the catalog
2.As defined by their role(s)
3.As defined by their access rights
4.As defined by the access type: CRUD, discover
5. As defined by the pre-defined filter
For example if they issue a get on a catalog that a party has no access they get an error response
Or if they try to modify an area of the catalog but do not have Write Access they get an error response
Normally we anticipate that the OAUTH2 or Open ID Connect are used as the authorization APIs and that ACL are establisher between authorized parties with regards to the content of the Catalog (i.e GET but also enable of update operations on specific entities).

...

Release Number

...

Date

...

Release led by:

...

Description

...

Release 1.0

...

04/15/2013

...

Pierre Gauthier
TM Forum
[email protected]

...

First Release of Draft Version of the Document.

...

Release 1.1

...

 

...

 

...

.

...

 

© TM Forum 2015. All Rights Reserved.