General Description of Catalogues API - sonata-nfv/tng-cat GitHub Wiki
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.
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 |
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
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-servicescurl -X POST --data-binary @vnfd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfscurl -X POST --data-binary @pd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/packagescurl -X POST --data-binary @sla-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptorscurl -X POST --data-binary @test-descriptor-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/testscurl -X POST --data-binary @slice-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/nstscurl -X POST --data-binary @pld_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/policiesThe 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.
To receive all descriptors you can use
curl -H "Content-type:application/x-yaml" <base URL>/api/v2/network-servicescurl -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfscurl -H "Content-type:application/x-yaml" <base URL>/api/v2/packagescurl -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptorscurl -H "Content-type:application/x-yaml" <base URL>/api/v2/testscurl -H "Content-type:application/x-yaml" <base URL>/api/v2/nstscurl -H "Content-type:application/x-yaml" <base URL>/api/v2/policiesThe 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.
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-servicescurl -X PUT --data-binary @vnfd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/vnfscurl -X PUT --data-binary @pd_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/packagescurl -X PUT --data-binary @sla-template-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/slas/template-descriptorscurl -X PUT --data-binary @test-descrtiptor-example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/testscurl -X PUT --data-binary @slice-template-example.yml.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/nstscurl -X PUT --data-binary @pld_example.yml -H "Content-type:application/x-yaml" <base URL>/api/v2/policiesTo 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}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.
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-packagescurl -X POST -H "Content-Type: application/octet-stream" -H "Content-Disposition: attachment; filename=MyExample.cfg" --data-binary @MyExample.cfg <base URL>/api/v2/filesHeader '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'
To receive a list of stored packages or files
curl -H "Content-Type: application/x-yaml" <base URL>/api/v2/tgo-packagescurl -H "Content-Type: application/x-yaml" <base URL>/api/v2/filesSame 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}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}