Skip to content

General Description of Catalogues API

Jump to bottom
Panagiotis Stavrianos edited this page Jun 30, 2018 · 7 revisions

In this page, examples are provided for the usage of the 5GTANGO Catalogue. Below, a brief description of the endpoints is given with meticulous examples are provided.

Api Reference

Strongly correlated with the environment of deploying the 5GTANGO Catalogues, the API route of <base_url> used in all endpoints is used as:

Environment <base_url>
Locally http://localhost:4011
Pre-Integration of 5GTANGO SP http://pre-int-sp-ath.5gtango.eu:4011
Pre-Integration of 5GTANGO V&V http://pre-int-vnv-bcn.5gtango.eu:4011
Integration of 5GTANGO SP http://int-sp-ath.5gtango.eu:4011
Integration of 5GTANGO V&V http://int-vnv-bcn.5gtango.eu:4011

Descriptors

The table summarizes the usage of 5GTANGO Catalogue, in terms of creating, retrieving, updating and deleting descriptors.

Action HTTP Method Endpoint
List all the available descriptors GET <base URL>/api/v2/{collection}
List all descriptors matching a specific filter(s) GET <base URL>/api/v2/{collection}?{attributeName}={value}
List only the last version for all descriptors GET <base URL>/api/v2/{collection}?version=last
List a descriptor using the UUID GET <base URL>/api/v2/{collection}/{id}
Store a descriptor in the Catalogue POST <base URL>/api/v2/{collection}
Update a descriptor using the naming triplet, i.e., name, vendor & version PUT <base URL>/api/v2/{collection}
Update a descriptor using the UUID PUT <base URL>/api/v2/{collection}/{id}
Set status of a descriptor using the UUID PUT <base URL>/api/v2/{collection}/{id}
Delete a descriptor using the naming triplet, i.e., name, vendor & version DELETE <base URL>/api/v2/{collection}
Delete a descriptor using the UUID DELETE <base URL>/api/v2/{collection}/{id}

where {collection} is one of network-services, vnfs, packages, slas/template-descriptors, tests, nsts, policies, denoting the MongoDB collection of each grouping. More specifically, examples are provided below

Method POST:

To upload a descriptor, you can use

curl -X POST --data-binary @nsd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/network-services
curl -X POST --data-binary @vnfd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfs
curl -X POST --data-binary @pd_example.yml -H "Content-type:application/x-yaml"  <base URL>/api/v2/packages
curl -X POST --data-binary @sla-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptors
curl -X POST --data-binary @test-descriptor-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/tests
curl -X POST --data-binary @slice-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/nsts
curl -X POST --data-binary @pld_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/policies

The Content-Type' header is substantially correlated with the format of the uploaded descriptor. For uploading a .json file, Content-Type' should be "Content-type:application/json". The uploaded file should be in the current directory and configured in the --data-binary field. The descriptor examples, which are mentioned in the examples above, are included in the samples/ folder.

Method GET

To receive all descriptors you can use

curl -H "Content-type:application/x-yaml" <base URL>/api/v2/network-services
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfs
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/packages
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptors
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/tests
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/nsts
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/policies

The Content-Type header defines the format of the returned response. This header can be configured also as "Content-type:application/json". In order to receive a certain descriptor by its ID, you can use

curl -H "Content-type:application/x-yaml" <base URL>/api/v2/network-services/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfs/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/packages/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptors/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/tests/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/nsts/{id}
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/policies/{id}

where {id} is the 128-bit universally unique identifier (UUID) number that is attached to the descriptor from the 5GTANGO Catalogue and returned as a response as soon as it is uploaded.

Method PUT

To update a descriptor is similar to the POST method, but it is required that an older version of the descriptor is stored in the Catalogues.

curl -X PUT --data-binary @nsd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/network-services
curl -X PUT --data-binary @vnfd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfs
curl -X PUT --data-binary @pd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/packages
curl -X PUT --data-binary @sla-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptors
curl -X PUT --data-binary @test-descrtiptor-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/tests
curl -X PUT --data-binary @slice-template-example.yml.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/nsts
curl -X PUT --data-binary @pld_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/policies

Method DELETE

To remove a descriptor by its ID

curl -X DELETE <base URL>/api/v2/network-services/{id}
curl -X DELETE <base URL>/api/v2/vnfs/{id}
curl -X DELETE <base URL>/api/v2/packages/{id}
curl -X DELETE <base URL>/api/v2/slas/template-descriptors/{id}
curl -X DELETE <base URL>/api/v2/tests/{id}
curl -X DELETE <base URL>/api/v2/nsts/{id}
curl -X DELETE <base URL>/api/v2/policies/{id}

Packages/Arbitrary Files

The API for 5GTANGO packages (tgo-package) and arbitrary files works very similar to the API for the descriptors. Packages are compressed files, hosting several individual entities, some of which are descriptors, arbitrary files, etc. In order to support the storage of this kind of files, additional endpoints are provided.

Method POST

In order to upload a package file or an arbitrary file, you can use

curl -X POST -H "Content-Type: application/zip" -H "Content-Disposition: attachment; filename=5gtango-test-package.tgo" --data-binary @5gtango-test-package.tgo <base URL>/api/v2/tgo-packages
curl -X POST -H "Content-Type: application/octet-stream" -H "Content-Disposition: attachment; filename=MyExample.cfg" --data-binary @MyExample.cfg <base URL>/api/v2/files

Header 'Content-Type' must be set to 'application/zip' for tgo-packages and application/octet-stream for files. Also, the HTTP header 'Content-Disposition' must be set to 'attachment; filename=name_of_the_package/file'

Method GET

To receive a list of stored packages or files

curl -H "Content-Type: application/x-yaml" <base URL>/api/v2/tgo-packages
curl -H "Content-Type: application/x-yaml" <base URL>/api/v2/files

Same as above, the header Content-Type defines the format of the response and can be configured also as application/json. To receive the raw data response of a package/arbitrary file, you can use

curl -H "Content-Type:application/zip" <base URL>/api/v2/tgo-packages/{id}
curl -H "Content-Type:application/octet-stream" <base URL>/api/v2/files/{id}

where {id} is the uuid attached to the package when it is uploaded. Yet, in order to receive only the metadata of the package/arbitrary file, the header Content-Type should be configured as application/json or application/x-yaml as

curl -H "Content-Type:application/x-yaml" <base URL>/api/v2/tgo-packages/{id}
curl -H "Content-Type:application/x-yaml" <base URL>/api/v2/files/{id}

Method DELETE

To remove a package file by its ID

curl -X DELETE <base URL>/api/v2/tgo-packages/{id}

The same approach is followed for the upload of arbitrary files

curl -X DELETE <base URL>/api/v2/files/{id}
Clone this wiki locally