sergiusens/packages_v2.md

## packages_v2.md

      
    Raw
  

              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.