Page tree

Versions Compared

Key

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

Hide If
special@authenticated
Note
titleTo access this API specification you wil need to be logged in

To login with your TM Forum account please click on the Login button below

Button Hyperlink
titleLogin
typeprimary
urlhttps://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable

Don't have an account? You can register by clicking here:

Button Hyperlink
titleRegister
typeprimary
urlhttps://www.tmforum.org/user-registration/
targettrue

Show If
special@authenticated

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 Product Offerings 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/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",

…..

}


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

 

© TM Forum 2015. All Rights Reserved.