Storage of Package Descriptors (PD) - sonata-nfv/tng-cat GitHub Wiki

In this page, the documentation of the API regarding the Package Descriptors (PD) storage is provided. It is recommended to read the structure of the advanced 5GTANGO package format in the link provided here. More specifically, the file of package descriptor has the default name of NFV Advanced Package Descriptor (NAPD) while the key element used is the detailed list of all included items in the 5GTANGO package. As the example details in this example, all included entities of the package are listed in the field package_content of the Package Descriptor. The corresponding extensions in the subfield source of the several files imply its nature of each one. The list of extensions is provided by the tng-schema repository in the link provided here. Additionally, the tng-sdk-package is considered of paramount importance in the structure of the 5GTANGO package. Last but not least, the API reference of <base_url> can be found here.

POST method

The POST method provides the upload of Package descriptors. The upload of a Package descriptor with json or yml extension format is available through a POST endpoint. For example, in order to upload the descriptor pd_example.json, the endpoint is composed as:

curl -X POST --data-binary @pd_example.json -H "Content-type:application/json" <base URL>/api/v2/packages

The header of Content-Type must be the corresponding with the format of the file upload. Also, the above endpoint assumes that the descriptor pd_example.json is located at the current directory. In any other occasion, the provision of the full path is a necessity. The Catalogues API will return a universally unique identifier (UUID) which is used to reference the specific descriptor in the endpoints below.

GET method

The GET method provides the retrieval of Package descriptors. Dependent on the request, different endpoints are created and analyzed below.

List all the available Package descriptors

The request can be created with json or yml extension format of the response. An example in json format is:

curl -H "Content-type:application/json" <base URL>/api/v2/packages

The response will be in the form of the corresponding format requested from above, regardless of the stored format.

List a descriptor using the UUID

The request of retrieving a descriptor using the uuid can be created with json or yml extension format of the response. An example in json format is:

curl -H "Content-type:application/json" <base URL>/api/v2/packages/c382c6d1-41c9-42cb-b442-44f434d86ba9

The response will be in the form of the corresponding format requested from above, regardless of the stored format.

List only the last version for all descriptors

The request of receiving a list of the last version for every descriptor can be created with json or yml extension format of the response. An example in json format is:

curl -H "Content-type:application/json" <base URL>/api/v2/packages?version=last

The response will be in the form of the corresponding format requested from above, regardless of the stored format.

List all descriptors matching a specific filter(s)

The request of receiving a list of all descriptors matching a specific filter(s) can be created with with json or yml extension format of the response. An example in json format is:

curl -H "Content-type:application/json" <base URL>/api/v2/packages?{attributeName1}={value1}[&{attributeName2}={value2}]

The fields in the brackets are not mandatory but they are compulsory in terms of providing multiple attribute names. The response will be in the form of the corresponding format requested from above. In order to efficiently use this endpoint, first, read the corresponding section.

PUT method

The PUT method provides the update of Package descriptors. Dependent on the request, different endpoints are created and analyzed below.

Update a descriptor using the UUID

This PUT method enables the update of a certain field of a descriptor with the provided UUID. The fields that can be changed are:

  • status field from the attached metadata of the Catalogue to the descriptor
  • the root level field of the uploaded descriptor The corresponding descriptor is provided below:
curl -X PUT  <base URL>/api/v2/packages/c382c6d1-41c9-42cb-b442-44f434d86ba9?<field>=<value>

In the example of the status field in the attached metadata of the Catalogue to the descriptor, the endpoint to update the value of the status to disabled is:

curl -X PUT  <base URL>/api/v2/packages/c382c6d1-41c9-42cb-b442-44f434d86ba9?status=disabled

Upload a Package descriptor as long as another descriptor exists in the Catalogue

This special endpoint is provided for the aim of versioning. The upload of a descriptor will be successful since a check for another given descriptor is successful also. For example, the upload of the descriptor pd_example.json is needed while the presence of the previously uploaded descriptor with uuid=c382c6d1-41c9-42cb-b442-44f434d86ba9 is necessary. The corresponding endpoint is provided below:

curl -X PUT --data-binary @pd_example.json -H "Content-type:application/json" <base URL>/api/v2/packages/c382c6d1-41c9-42cb-b442-44f434d86ba9

The format of the provided header with Content-Type must be the corresponding extension of the descriptor to be uploaded. Instead of using the uuid to check for a specific descriptor, the naming triplet of name, vendor, version can be supported:

curl -X PUT --data-binary @pd_example.json -H "Content-type:application/json" <base URL>/api/v2/packages?name={name1}&vendor={vendor1}&version={1.0}

The above example checks for the presence of a descriptor with naming triplet name={name1}&vendor={vendor1}&version={1.0} and uploads the descriptor pd_example.json if the presence of the previous descriptor is valid.

DELETE method

The DELETE method provides the deletion of Package descriptors and the included files of the 5GTANGO package, namely the Package File, Arbitrary Files and the Descriptors. The 5GTANGO Catalogue provided this functionality through the detailed list of all included items in the 5GTANGO package. Dependent on the request, different endpoints are created and analyzed below.

Delete a descriptor using the UUID

In order to delete a specific descriptor using its UUID, the endpoint is:

curl -X DELETE <base URL>/api/v2/packages/c382c6d1-41c9-42cb-b442-44f434d86ba9

Delete a descriptor using the triplet attributes of name, vendor and version

In order to delete a specific descriptor using its naming triplet attributes of name, vendor and version, a special case of using these attributes takes place. For example, to delete a descriptor which contains a name field with value name1, a vendor field with value vendor1 and a version field with value 1.0, the endpoint is:

curl -X DELETE <base URL>/api/v2/packages?name={name1}&vendor={vendor1}&version={1.0}
⚠️ **GitHub.com Fallback** ⚠️