APIs

The packager can be executed as service (bare metal or running inside a container) and offers a REST API to which packages can be uploaded to be unpackaged. The resulting artifacts are then pushed to the configured storage backend. The available REST API follows a asynchronous design which means that it directly returns with 200 after a package is uploaded and the unpackaging process is triggered. At this point the unpackaging process is still running and may still fail.

To notify a client about the end of an unpackaging process or an error, we use a callback mechanism: The user can specify a URL in his request the packager calls this URL once the packaging process finishes or an error occurs. More details can be found in the following.

Swagger-based REST API documentation

We use Swagger (OpenAPI) to specify and document the REST API of the packager. This documentation is automatically generated from the Python code and models without any additional human interaction. This ensures that the documentation is always in sync with the code.

You can find it here: REST API specification

Callback

Callbacks are send from the packager to the callback_url given in the unpackaging request once the unpackaging is done. Request type is POST. Expected response is 200 OK.

The callback endpoint is specified with this OpenAPI model.

An example request body looks like this:

{  
    "event_name":"onPackageChangeEvent",
    "package_id":"24c616cf-fe01-4c08-ae44-45d43ae67576",
    "package_location":"http://tng-cat:4011/catalogues/api/v2/tgo-packages/24c616cf-fe01-4c08-ae44-45d43ae67576",
    "package_metadata":null,
    "package_process_uuid":"d5cea225-033f-4fc6-816f-4a642461086a",
    "package_process_status": "success"
}

The package_metadata field can contain arbitrary complex data structures, usually based on the package descriptor of the unpackaged package.

The package_process_uuid can be used by clients to correlate a received callback request to the initial package upload request that triggered the unpackaging procedure.

Examples

The following examples assume that an instance of tng-sdk-package is running locally using port 5099 and that there the following endpoint is available to perform callbacks: http://127.0.0.1:8000/api/v1/packages/on-change.

This setup can be created as follows:

# terminal 1 (run tng-sdk-package service locally without connection to a storage backend, e.g., a catalog)
tng-pkg -s -v --store-skip

# terminal 2 (callback dummy server)
python misc/callback_mock.py

Now the following unpackaging examples can be performed: