Refresh

snap_refresh

Introduced in version 1

Summary: POST /v2/snaps/refresh

Get the best revisions to install/refresh for the given snaps.

The request must contain the following mandatory headers:

  • Snap-Device-Architecture: the device's architecture

  • Snap-Device-Series: the device's series, the only supported value so far is '16'.

  • User-Agent: the client's information

  • Snap-Refresh-Reason: the client refresh reason. Set primarily by the snapd client as scheduled indicating the operation is performed in background. If necessary, the store can degrade performance with limited impacts in user perception.

Also it must include a JSON encoded body representing a dict with the following information (everything mandatory unless indicated):

  • context: information about the currently installed snaps (which is important to be considered if gating for validation purposes of gated snaps that are actually refreshed or installed), a list of dicts each containing:

    • instance-key: a unique identifier in the request that relates this context information with what is being refreshed (it's a free form string, no constraints).

    • snap-id: the id of the installed snap.

    • revision: the revision installed (an integer).

    • tracking-channel: the channel that the installed snap is tracking in a simple string form ("stable", "mytrack/candidate", etc.).

    • ignore-validation: an optional boolean (default to false) to indicate if proper validation should be ignored if the snap is a gated one.

    • refreshed-date: the date in which this snap revision was installed in the caller's system, in ISO 8601 format, optional.

    • cohort-key: an optional key identifying a cohort.

Note that for the case of snapd amend/refreshing a locally installed snap, as it would use an install action to get information for the snap, that snap shouldn't be included in this context.

  • assertion-max-formats: A mapping of assertion-types and the max-format requested by the client for that type.

  • actions: a list of the intended actions from the client, one action per snap, each object containing an action field indicating the intended action (a string with one of the install, refresh, or refresh-all values) and some more fields according to the defined action in each case:

  • if action == install: used for new installations and to refresh locally-installed snaps.

    • instance-key: a unique identifier for the action.

    • name: the snap name (if snap-id is given, this field must not be sent).

    • snap-id: the snap id (if name is was given, this field must not be sent).

    • channel: the channel to install from (optional, defaults to stable, must not be sent if revision is present).

    • revision: an optional integer to indicate the explicit requested revision; must not be sent if channel is given.

    • ignore-validation: an optional boolean (default to false) to indicate if proper validation should be ignored if the snap is a gated one.

    • epoch: epochs information to apply restrictions if the snap was locally-installed in the device, optional; its structure is a dictionary with two keys, read and write, each holding a list of integers.

    • cohort-key: an optional key identifying a cohort. Overrides any cohort-key obtained via context.

  • if action == download: fields, behaviour and rules here are exactly the same as for the install action; this is for the case of the client needing all the info like in an install situation but not really installing the snap (e.g. prepare an image).

  • if action == refresh: used to refresh installed snaps to a more suitable revision.

    • instance-key: a unique identifier for the action (which must relate to a context entry).

    • snap-id: the snap id.

    • revision: an optional integer to indicate the explicit requested revision; must be missing if channel is present.

    • channel: the channel to refresh to (optional, defaults to the tracking channel in the context; must be missing if revision is present).

    • ignore-validation: an optional boolean (default to what the context says) to indicate if proper validation should be ignored if the snap is a gated one.

    • cohort-key: an optional key identifying a cohort. Overrides any cohort-key obtained via context.

  • if action == refresh-all: there must not be other fields (as all the needed information is already present in the context).

  • if action == fetch-assertions: used to fetch a list of assertion-stream-urls for a list of assertions.

    • key: a key to group this set of requested assertions; this is returned in the response so clients are able to make grouped assertion requests.

    • assertions: A list of assertions requested in this group. Each assertion request is a JSON object. There are two allowed types of requests:

      1. primary-key based requests (supported for all assertion types). Allowed primary-key request object fields are (required unless otherwise noted):

        • type: assertion type

        • primary-key: the primary-key used to lookup the assertion

        • if-newer-than (optional): only return the assertion in assertion-stream-urls if there is a newer revision than the requested one.

      2. sequence-key based requests (supported for sequence-forming assertion types). Allowed sequence-key request object fields are (required unless otherwise noted):

        • type: assertion type

        • sequence-key: the sequence-key used to lookup the assertion

        • if-newer-than (optional): only return the assertion in assertion-stream-urls if there is a newer revision than the requested one.

        • if-sequence-newer-than (optional): only return the assertion in assertion-stream-urls if there is a newer sequence member than the requested one.

        • if-sequence-equal-or-newer-than (optional): if the latest available sequence is equal to if-sequence-equal-or-newer-than, return the assertion if its revision is newer than if-newer-than. Or return the latest revision of the latest sequence of the assertion if the latest available sequence is higher than if-sequence-equal-or-newer-than (regardless of the revision value in if-newer-than). If if-newer-than is not present, return the assertion if the sequence is equal or newer than requested.

        • sequence (optional): alternative way of specifying the sequence part of sequence-forming assertion's primary key to get the latest revision of that assertion.

      if-sequence-newer-than, if-sequence-equal-or-newer-than and sequence are exclusive and are not allowed to be specified together.

  • fields: a list of field names (a string each) indicating which fields are needed in the response payload; it's optional, defaults to return the created-at, download, license, name, prices, publisher, revision, snap-id, summary, title, type and version fields.

Whenever incompatible fields are sent (e.g. name and snap-id simultaneously in an install), that snap will be "errored", and a specific error for the inconsistency will be returned.

A successful response will have a dict with one key, results, containing a list with one object per snap in the requested actions:

  • result: a string install, refresh, 'fetch-assertions' or error; in the first three cases this item has all the needed info for the client to go ahead with its intention, otherwise there was an error with the requested snap and some information may be missing below.

  • instance-key: a unique identifier that relates each item in the response with the original request item.

  • snap-id: the id of the snap (may not be present, e.g. if the original request was to install and the name provided was not found).

  • name: the name of the snap (may not be present, e.g. if the original request was to refresh but the snap is not longer available).

  • error: dictionary containing keys code and message, with error information if result is error.

  • snap: a dictionary with the requested fields (see fields above) for the given snap. If requested fields is empty, this snap field will be empty.

  • effective-channel: string, the channel where the corresponding snap revision is effectively released to (may differ from the requested channel); this field will be present only when the request was per channel, and missing if was done by revision.

  • released-at: string, when snap revision was released into its channel, the value will be encoded in ISO 8601 and will be null if there is no candidate revision.

  • redirect-channel: string, the channel that shall be used for future refreshes instead of the current one; this field will be present only when there was a redirection set for the snap

  • key: string. This is only used for fetch-assertions actions, and is the same key that was used by the client in its request. It is used to group a set of assertion requests.

  • assertion-stream-urls: list of urls of updated assertions. Only used for fetch-assertions actions.

  • error-list: A list of errors in an otherwise successful request. Currently, only used for fetch-assertions actions. A fetch-assertions action can potentially have mixed results (some assertions found, others not-found, or with a key error). This allows the endpoint to return successful results in assertion-stream-urls and errors in error-list. Each error includes the following properties: code, message, type, and primary-key or sequence-key depending on the request.

A complete error may happen (beyond normal cases like JSON badly encoded, etc) if the request has the following serious internal problems, producing a 400 BAD REQUEST:

  • a refresh-all action was combined with a refresh and/or install actions.

  • an unknown action is found.

When there are authentication errors, the server will follow the "return everything it can" reasoning, and provide information for the public snaps only, returning a regular "not found" for those snaps that are not visible by the user/device.

These authentication errors or other "global" errors will be informed through an extra key in the result, next to results called error-list, as follows:

{"results": [{"result": ..., "snap-id": ..., "name": ..., ...}, ...],
 "error-list": [{"code": ..., "message": ...}, ...]}

Each error dict will have a code, a message, and optionally an URL. Note that both results and error-list will always be present, just empty if we didn't have any positive result or any error respectively.

Any potential rewrite that is needed, if the snapdevicegw is running as a local proxy is handled in this function. Which means that the @proxy.maybe_proxy decorator with modifiers cannot be used!

snap_refresh changelog

  • Version 26: Added sequence-key lookup support to 'fetch-assertions' actions.

  • Version 21: Added top level 'assertion-max-formats'. Add 'fetch-assertions' actions and results.

  • Version 15: Media 'width' & 'height' may be populated with integers.

  • Version 14: Added the 'redirect-channel' field to the response.

  • Version 13: Removed cohort-create.

  • Version 12: Added support for 'Snap-Refresh-Reason' header

  • Version 10: Added support for 'released-at' field.

  • Version 9: Added cohort-key in context and actions.

  • Version 8: Added epoch in context.

  • Version 7: Added cohort-create to action and cohort-key to response.

  • Version 5: allow_unauthenticated snaps can be downloaded even if store authentication fails

  • Version 4: Added support for 'website' field.

  • Version 2: Added extra field to error items.

Request JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "actions": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "action": {
                        "type": "string"
                    },
                    "assertions": {
                        "introduced_at": 21,
                        "items": {
                            "anyOf": [
                                {
                                    "additionalProperties": false,
                                    "introduced_at": 21,
                                    "properties": {
                                        "if-newer-than": {
                                            "introduced_at": 21,
                                            "maximum": 9223372036854775807,
                                            "minimum": 0,
                                            "type": "integer"
                                        },
                                        "primary-key": {
                                            "introduced_at": 21,
                                            "items": {
                                                "introduced_at": 21,
                                                "type": "string"
                                            },
                                            "type": "array"
                                        },
                                        "type": {
                                            "introduced_at": 21,
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "primary-key"
                                    ],
                                    "type": "object"
                                },
                                {
                                    "additionalProperties": false,
                                    "introduced_at": 26,
                                    "properties": {
                                        "if-newer-than": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 0,
                                            "type": "integer"
                                        },
                                        "if-sequence-newer-than": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 1,
                                            "type": "integer"
                                        },
                                        "sequence-key": {
                                            "items": {
                                                "type": "string"
                                            },
                                            "type": "array"
                                        },
                                        "type": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "sequence-key"
                                    ],
                                    "type": "object"
                                },
                                {
                                    "additionalProperties": false,
                                    "introduced_at": 26,
                                    "properties": {
                                        "if-newer-than": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 0,
                                            "type": "integer"
                                        },
                                        "if-sequence-equal-or-newer-than": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 1,
                                            "type": "integer"
                                        },
                                        "sequence-key": {
                                            "items": {
                                                "type": "string"
                                            },
                                            "type": "array"
                                        },
                                        "type": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "sequence-key"
                                    ],
                                    "type": "object"
                                },
                                {
                                    "additionalProperties": false,
                                    "introduced_at": 26,
                                    "properties": {
                                        "if-newer-than": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 0,
                                            "type": "integer"
                                        },
                                        "sequence": {
                                            "maximum": 9223372036854775807,
                                            "minimum": 1,
                                            "type": "integer"
                                        },
                                        "sequence-key": {
                                            "items": {
                                                "type": "string"
                                            },
                                            "type": "array"
                                        },
                                        "type": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "sequence-key"
                                    ],
                                    "type": "object"
                                }
                            ]
                        },
                        "type": "array"
                    },
                    "channel": {
                        "type": "string"
                    },
                    "cohort-key": {
                        "introduced_at": 9,
                        "type": "string"
                    },
                    "epoch": {
                        "additionalProperties": false,
                        "properties": {
                            "read": {
                                "items": {
                                    "type": "number"
                                },
                                "type": "array"
                            },
                            "write": {
                                "items": {
                                    "type": "number"
                                },
                                "type": "array"
                            }
                        },
                        "required": [
                            "read",
                            "write"
                        ],
                        "type": [
                            "object",
                            "null"
                        ]
                    },
                    "ignore-validation": {
                        "type": "boolean"
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "key": {
                        "introduced_at": 21,
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "revision": {
                        "type": "number"
                    },
                    "snap-id": {
                        "type": "string"
                    }
                },
                "required": [
                    "action"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "assertion-max-formats": {
            "additionalProperties": {
                "maximum": 9223372036854775807,
                "minimum": -1,
                "type": "integer"
            },
            "introduced_at": 21,
            "type": "object"
        },
        "context": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "cohort-key": {
                        "introduced_at": 9,
                        "type": "string"
                    },
                    "epoch": {
                        "additionalProperties": false,
                        "introduced_at": 8,
                        "properties": {
                            "read": {
                                "items": {
                                    "type": "number"
                                },
                                "type": "array"
                            },
                            "write": {
                                "items": {
                                    "type": "number"
                                },
                                "type": "array"
                            }
                        },
                        "required": [
                            "read",
                            "write"
                        ],
                        "type": [
                            "object",
                            "null"
                        ]
                    },
                    "ignore-validation": {
                        "type": "boolean"
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "refreshed-date": {
                        "type": "string"
                    },
                    "revision": {
                        "type": "number"
                    },
                    "snap-id": {
                        "type": "string"
                    },
                    "tracking-channel": {
                        "type": "string"
                    }
                },
                "required": [
                    "snap-id",
                    "revision",
                    "tracking-channel",
                    "instance-key"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "fields": {
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    },
    "required": [
        "context",
        "actions"
    ],
    "type": "object"
}

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "error-list": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "message"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "results": {
            "additionalProperties": false,
            "anyOf": [
                {
                    "required": [
                        "instance-key",
                        "snap-id",
                        "name",
                        "result"
                    ]
                },
                {
                    "required": [
                        "assertion-stream-urls",
                        "key",
                        "result"
                    ]
                }
            ],
            "items": {
                "properties": {
                    "assertion-stream-urls": {
                        "introduced_at": 21,
                        "items": {
                            "introduced_at": 21,
                            "type": "string"
                        },
                        "type": "array"
                    },
                    "cohort-key": {
                        "introduced_at": 7,
                        "type": "string"
                    },
                    "effective-channel": {
                        "type": "string"
                    },
                    "error": {
                        "additionalProperties": false,
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "extra": {
                                "introduced_at": 2,
                                "type": "object"
                            },
                            "message": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "code",
                            "message"
                        ],
                        "type": "object"
                    },
                    "error-list": {
                        "introduced_at": 21,
                        "items": {
                            "additionalProperties": false,
                            "introduced_at": 21,
                            "properties": {
                                "code": {
                                    "introduced_at": 21,
                                    "type": "string"
                                },
                                "message": {
                                    "introduced_at": 21,
                                    "type": "string"
                                },
                                "primary-key": {
                                    "introduced_at": 21,
                                    "items": {
                                        "introduced_at": 21,
                                        "type": "string"
                                    },
                                    "type": "array"
                                },
                                "sequence-key": {
                                    "introduced_at": 26,
                                    "items": {
                                        "type": "string"
                                    },
                                    "type": "array"
                                },
                                "type": {
                                    "introduced_at": 21,
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        },
                        "type": "array"
                    },
                    "instance-key": {
                        "type": "string"
                    },
                    "key": {
                        "introduced_at": 21,
                        "type": "string"
                    },
                    "name": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "redirect-channel": {
                        "introduced_at": 14,
                        "type": "string"
                    },
                    "released-at": {
                        "introduced_at": 10,
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "result": {
                        "type": "string"
                    },
                    "snap": {
                        "oneOf": [
                            {
                                "type": "null"
                            },
                            {
                                "additionalProperties": false,
                                "properties": {
                                    "architectures": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array"
                                    },
                                    "base": {
                                        "oneOf": [
                                            {
                                                "type": "null"
                                            },
                                            {
                                                "type": "string"
                                            }
                                        ]
                                    },
                                    "channel": {
                                        "type": "string"
                                    },
                                    "common-ids": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array"
                                    },
                                    "confinement": {
                                        "type": "string"
                                    },
                                    "contact": {
                                        "type": "string"
                                    },
                                    "created-at": {
                                        "type": "string"
                                    },
                                    "description": {
                                        "type": "string"
                                    },
                                    "download": {
                                        "additionalProperties": false,
                                        "properties": {
                                            "deltas": {
                                                "items": {
                                                    "additionalProperties": false,
                                                    "properties": {
                                                        "format": {
                                                            "type": "string"
                                                        },
                                                        "sha3-384": {
                                                            "type": "string"
                                                        },
                                                        "size": {
                                                            "type": "number"
                                                        },
                                                        "source": {
                                                            "type": "number"
                                                        },
                                                        "target": {
                                                            "type": "number"
                                                        },
                                                        "url": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "required": [
                                                        "format",
                                                        "sha3-384",
                                                        "size",
                                                        "source",
                                                        "target",
                                                        "url"
                                                    ],
                                                    "type": "object"
                                                },
                                                "type": "array"
                                            },
                                            "sha3-384": {
                                                "type": "string"
                                            },
                                            "size": {
                                                "type": "number"
                                            },
                                            "url": {
                                                "type": "string"
                                            }
                                        },
                                        "required": [
                                            "sha3-384",
                                            "size",
                                            "url",
                                            "deltas"
                                        ],
                                        "type": "object"
                                    },
                                    "epoch": {
                                        "additionalProperties": false,
                                        "properties": {
                                            "read": {
                                                "items": {
                                                    "type": "number"
                                                },
                                                "type": "array"
                                            },
                                            "write": {
                                                "items": {
                                                    "type": "number"
                                                },
                                                "type": "array"
                                            }
                                        },
                                        "required": [
                                            "read",
                                            "write"
                                        ],
                                        "type": [
                                            "object",
                                            "null"
                                        ]
                                    },
                                    "gated-snap-ids": {
                                        "items": {
                                            "type": "string"
                                        },
                                        "type": "array"
                                    },
                                    "license": {
                                        "type": "string"
                                    },
                                    "media": {
                                        "items": {
                                            "additionalProperties": false,
                                            "properties": {
                                                "height": {
                                                    "type": [
                                                        "null",
                                                        "integer"
                                                    ]
                                                },
                                                "type": {
                                                    "type": "string"
                                                },
                                                "url": {
                                                    "type": "string"
                                                },
                                                "width": {
                                                    "type": [
                                                        "null",
                                                        "integer"
                                                    ]
                                                }
                                            },
                                            "required": [
                                                "type",
                                                "url",
                                                "width",
                                                "height"
                                            ],
                                            "type": "object"
                                        },
                                        "type": "array"
                                    },
                                    "name": {
                                        "type": "string"
                                    },
                                    "prices": {
                                        "type": "object"
                                    },
                                    "private": {
                                        "type": "boolean"
                                    },
                                    "publisher": {
                                        "additionalProperties": false,
                                        "properties": {
                                            "display-name": {
                                                "type": "string"
                                            },
                                            "id": {
                                                "type": "string"
                                            },
                                            "username": {
                                                "type": "string"
                                            },
                                            "validation": {
                                                "introduced_at": 3,
                                                "type": "string"
                                            }
                                        },
                                        "required": [
                                            "id",
                                            "username",
                                            "display-name"
                                        ],
                                        "type": "object"
                                    },
                                    "revision": {
                                        "type": "number"
                                    },
                                    "snap-id": {
                                        "type": "string"
                                    },
                                    "snap-yaml": {
                                        "type": "string"
                                    },
                                    "summary": {
                                        "type": "string"
                                    },
                                    "title": {
                                        "type": "string"
                                    },
                                    "type": {
                                        "type": "string"
                                    },
                                    "version": {
                                        "type": "string"
                                    },
                                    "website": {
                                        "introduced_at": 4,
                                        "oneOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "null"
                                            }
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        ]
                    },
                    "snap-id": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "results",
        "error-list"
    ],
    "type": "object"
}

© 2019 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.