Packages management

This wiki page is part of the usage documentation of the tng-gtk-common module.

Context

Packages constitute the unit for uploading information into the Catalogue. The package has to go through an un-packaging and validation process before being accepted, as shown in the next figure (Figure 5.4 from the D2.2 Architecture Design project deliverable).

This package on-boarding is common to the V&V platform and to the SP. It is also a asynchronous process.

You can get examples of packages here (the good one) and here (the malformed one).

On-boarding

On-boarding (i.e., uploading) a package is an asynchronous process that involves several components until the package is stored in the Catalogue:

1. the API Gateway component;
2. this component, the Gatekeeper Common;
3. the Packager component;
4. and the already mentioned Catalogue.

On-boarding a package can be done by the following command:

$ curl -X POST :api_root/packages -F "package=@./5gtango-ns-package-example.tgo"

The package field is the only one that is mandatory, but there are a number of optional ones that you can check here.

Expected returned data is:

• HTTP code 200 (Ok) if the package is accepted for processing, with a JSON object including the package_processing_uuid (see Querying the status, below);
• HTTP code 400 (Bad Request), if the file is not found, has the wrong MEDIA type, etc.

Querying

On-boarding processes

We may query the on-boarding process by issuing

$ curl :api_root/packages/status/:package_processing_uuid

Expected returned data is:

• HTTP code 200 (Ok) if the package processing UUID is found, with the processing status in the body (JSON format);
• HTTP code 400 (Bad Request), if the :package_processing_uuid is mal-formed;
• HTTP code 404 (Not Found), if the package processing is not found.

Many packages

Querying all existing packages can be done using the following command (default values for DEFAULT_PAGE_SIZE and DEFAULT_PAGE_NUMBER mentioned above are used):

$ curl :api_root/packages

If different default values for the starting page number and the number of records per page are needed, these can be used as query parameters:

$ curl ":api_root/packages?page_size=20&page_number=2"

Note the "" used around the command, in order for the shell used to consider the & as part of the command, instead of considering it a background process command.

Expected returned data is:

• HTTP code 200 (Ok) with an array of package's metadata in the body (JSON format), or an empty array ([]) if none is found according to the parameters passed;

A single package

A specific package's metadata can be fetched using the following command:

$ curl :api_root/packages/:package_uuid

Expected returned data is:

• HTTP code 200 (Ok) if the package is found, with the package's metadata in the body (JSON format);
• HTTP code 400 (Bad Request), if the :package_uuid is mal-formed;
• HTTP code 404 (Not Found), if the package is not found.

In case we want to download the package's file, we can use the following command:

$ curl :api_root/packages/:package_uuid/package-file

Expected returned data is:

• HTTP code 200 (Ok) if the package is found, with the package's file in the body (binary format);
• HTTP code 400 (Bad Request), if the :package_uuid is mal-formed;
• HTTP code 404 (Not Found), if the package is not found.

In case we want to download the any of the other files the package may contain, we can use the following command, where the :file_uuid can be fetched from the packages metada:

$ curl :api_root/packages/:package_uuid/files/:file_uuid

Expected returned data is:

• HTTP code 200 (Ok) if the file is found, with its content in the body (binary format);
• HTTP code 400 (Bad Request), if the :package_uuid or :file_uuid is mal-formed;
• HTTP code 404 (Not Found), if the package or the file is not found.

Deleting

We may delete an on-boarded package by issuing the following command:

$ curl -X DELETE :api_root/packages/:package_uuid

Expected returned data is:

• HTTP code 204 (No Content) if the package is found and successfuly deleted (the body will be empty);
• HTTP code 400 (Bad Request), if the :package_uuid is mal-formed;
• HTTP code 404 (Not Found), if the package is not found.

Options

We may query which operations are allowed with the HTTP verb OPTIONS, by issuing the following command:

$ curl -X OPTIONS :api_root/packages

* `HTTP` code `200` (`No Content`) if the package options are defined;