rfc: webdm api

packages_v2.md

Requesting packages

This api is used to work against snap packages. The packages api mixes up results from the store and installed system.

Searching and listing

To get all packages

GET /api/v2/packages/

To make fine grained requests, the http GET request can have query parameter:

• types
• installed_only

Of which:

• types is a comma separated list of snap types, i.e.; oem, device, app, framework.
• installed_only can be true or false, if true it avoids checking for store results.

Results

A request with query parameters that look like

    http://[host]:4200/?types=app,framework&installed_only=true

Results in a payload similar to:

    [
        {
            "status": "installed",
            "name": "camlistore.sergiusens",
            "version": "0.8",
            "vendor": "Sergio Schvezov",
            "icon": "meta/icon.png",
            "type": "app",
            "ui_port": 8080,
            "ui_uri": "http"
        },
        {
            "status": "installed",
            "name": "webdm",
            "version": "0.1",
            "vendor": "Sergio Schvezov",
            "icon": "meta/icon.png",
            "type": "framework",
            "ui_port": 8081,
            "ui_uri": "https"
        },
        {
            "status": "uninstalled",
            "name": "pastebinit.mvo",
            "version": "0.8",
            "vendor": "Michael Vogt",
            "icon": "http: //storeurl/icon.png",
            "ratings_average": 4.5,
            "price": 0,
            "type": "app"
        }
    ]

Fields

• status: can be either uninstalled, installing, installed, updating or uninstalling.
• name: the package name.
• version: a string representing the version.
• vendor: a string representing the vendor.
• icon: a url to the package icon.
• ratings_average: a float representing the rating from the store
• price: a float representing the price for the store.
• type: the type of snappy package, can be oem, framework, app or device.
• services: TBD if want exposed at all (maybe to start/stop services).
• ui_port: port the webdm can use to open.
• ui_uri: resource handler to use to open the ui.

Example of use for ui components

A user interface can craft a url to open by using the ui_port and ui_uri into a full URL with the hostame, e.g.; if the ui_port is 8080 and the ui_uri is http the to access the ui with hostname of webdm.local it will use http://webdm.local:8080; if instead ui_uri where to be ssh the crafted resource would be ssh://webdm.local:8080

Paging

TBD

Querying

To get a specific package

GET /api/v2/packages/[package_name]

To make fine grained requests, the http request can have query parameters that act as filters

If installed_only is used and the package is not installed a 404 shall be returned.

Results

Uninstalled

The result is similar to a general listing.

    {
        "status": "uninstalled",
        "name": "camlistore.sergiusens",
        "version": "0.8",
        "vendor": "Sergio Schvezov",
        "icon": "meta/icon.png",
        "type": "app"
    }

Installed

The result is similar to a general listing.

TODO define services listing.

    {
        "status": "installed",
        "name": "camlistore.sergiusens",
        "version": "0.8",
        "vendor": "Sergio Schvezov",
        "icon": "meta/icon.png",
        "type": "app",
        "ui_port": 8080,
        "ui_uri": "http"
    }

Installing and Updating

Installing shall have 2 extra entries:

    {
        "status": "installing",
        "download_progress": 100,
        "status_message": "Applying",
        "name": "camlistore.sergiusens",
        "version": "0.8",
        "vendor": "Sergio Schvezov",
        "icon": "meta/icon.png",
        "type": "app",
        "ui_port": 8080,
        "ui_uri": "http"
    }

Differences to an installed app:

• status: is set to either installing or updating depending on the action.
• progress: is an integer with the current progress.
• status_message: is used when the is no progress possible but some feedback is required

Installing

Installing is accomplished with an http PUT to

PUT /api/v2/packages/[package_name]

As this is idempotent, if the package is already installed, nothing will happen, even if there is an update for the package trying to be updated.

Results

• 200: If the package was already installed, a 200 is returned.
• 202: On success, the http code 202 shall be returned, updates on progress can be obtained by sending GET to the general listing or specific package query.
• 400: If the package is in the process of being installed already, a 400 is returned.
• 404: If the package does not exist a 404 is returned.
• 5xx: On system errors.

Updating

Updating is similar to installing but uses the UPGRADE http command instead.

UPGRADE /api/v2/packages/[snappy_package_name]

Results

• 202: On success, the http code 202 shall be returned, updates on progress can be obtained by sending GET to the general listing or specific package query.
• 400: If the package is in the process of being updated already, a 400 is returned.
• 404: If the package does not exist a 404 is returned.
• 5xx: On system errors.

Uninstalling

Uninstalling is similar to installing but uses the DELETE http command instead.

DELETE /api/v2/packages/[snappy_package_name]

Results

• 202: On success, the http code 202 shall be returned, updates on progress can be obtained by sending GET to the general listing or specific package query.
• 400: If the package is in the process of being uninstalled already, a 400 is returned.
• 404: If the package does not exist a 404 is returned.
• 5xx: On system errors.

This looks fine, my gut feeling is that we should make the store have exactly the same output (or we try to have the same output as the store) as this would allow remote installs etc in the future, i.e. webdm "manages" multiple snappy boxes for the same user.

+1 to matching the store output exactly, and adding services to the store apis

I'm good with matching the store output, but the store json seems to come from the deb days.

How can I tell if an update is available for a package?
How about HTTP PATCH rather than upgrade header for starting an upgrade?

Do we want rollback? Maybe work in a similar way to update, send a PATCH request with a new version number (which would mean that pacakge GET also returns a list of available versions)