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
scheduledindicating 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 tofalse) 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. -
validation-sets: optional array of validation set assertions' primary keys governing the decision on the snap existence on the system. Each key is represented as a 4 element long array of strings:["<series>", "<account-id>", "<name>", "<sequence>"].
-
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 theinstall,refresh, orrefresh-allvalues) 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 tofalse) 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,readandwrite, each holding a list of integers. -
cohort-key: an optional key identifying a cohort. -
validation-sets: optional array of validation set assertions' primary keys governing the decision on the snap existence on the system. Each key is represented as a 4 element long array of strings:["<series>", "<account-id>", "<name>", "<sequence>"].
-
-
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. -
validation-sets: optional array of validation set assertions' primary keys governing the decision on the snap existence on the system. Each key is represented as a 4 element long array of strings:["<series>", "<account-id>", "<name>", "<sequence>"].
-
-
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:-
primary-keybased requests (supported for all assertion types). Allowedprimary-keyrequest 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.
-
-
sequence-keybased requests (supported for sequence-forming assertion types). Allowedsequence-keyrequest 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 toif-sequence-equal-or-newer-than, return the assertion if its revision is newer thanif-newer-than. Or return the latest revision of the latest sequence of the assertion if the latest available sequence is higher thanif-sequence-equal-or-newer-than(regardless of the revision value in if-newer-than). Ifif-newer-thanis 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-thanandsequenceare 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 (inside thesnapdict described below); it's optional, defaults to return thecreated-at,download,license,name,prices,publisher,revision,snap-id,summary,title,typeandversionfields. Valid fields are:architectures,base,common-ids,confinement,contact,created-at,description,download,epoch,gated-snap-ids,license,links,media,name,prices,private,publisher,resources,revision,snap-id,snap-yaml,summary,title,type,version,website.
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 stringinstall,refresh, 'fetch-assertions' orerror; 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 keyscodeandmessage, with error information ifresultiserror. -
snap: a dictionary with the requested fields (seefieldsabove) for the given snap. If requestedfieldsis 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 inassertion-stream-urlsand errors inerror-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-allaction was combined with arefreshand/orinstallactions. -
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.
snap_refresh changelog
- Version 55: Fixed bug in held field for held snaps.
- Version 54: Added optional held field for held snaps.
- Version 37: Added support for validation-sets based snap refresh revision access.
- 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" }, "validation-sets": { "introduced_at": 37, "items": { "introduced_at": 37, "items": { "introduced_at": 37, "type": "string" }, "maxItems": 4, "minItems": 4, "type": "array" }, "minItems": 1, "type": "array" } }, "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" ] }, "held": { "additionalProperties": false, "introduced_at": 54, "properties": { "by": { "introduced_at": 54, "items": { "introduced_at": 54, "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "by" ], "type": "object" }, "ignore-validation": { "type": "boolean" }, "instance-key": { "type": "string" }, "refreshed-date": { "type": "string" }, "revision": { "type": "number" }, "snap-id": { "type": "string" }, "tracking-channel": { "type": "string" }, "validation-sets": { "introduced_at": 37, "items": { "introduced_at": 37, "items": { "introduced_at": 37, "type": "string" }, "maxItems": 4, "minItems": 4, "type": "array" }, "minItems": 1, "type": "array" } }, "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" }, "links": { "additionalProperties": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "introduced_at": 21, "type": [ "object", "null" ] }, "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" }, "resources": { "introduced_at": 57, "items": { "additionalProperties": false, "introduced_at": 57, "properties": { "created-at": { "introduced_at": 57, "type": "string" }, "description": { "introduced_at": 57, "type": "string" }, "download": { "introduced_at": 57, "properties": { "sha3-384": { "introduced_at": 57, "type": "string" }, "size": { "introduced_at": 57, "type": "integer" }, "url": { "introduced_at": 57, "type": "string" } }, "type": "object" }, "name": { "introduced_at": 57, "type": "string" }, "revision": { "introduced_at": 57, "type": "integer" }, "type": { "introduced_at": 57, "type": "string" }, "version": { "introduced_at": 57, "type": [ "null", "string" ] } }, "type": "object" }, "type": "array" }, "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" }