.. _snaps: ======================== Snaps ======================== Introduction ------------ No introduction documentation yet. .. _api-snap-releases: Snap Releases ------------------------------------------------------------------- *Introduced in version 1* .. http:GET:: /api/v2/snaps/(?P[\\w-]+)/releases Fetch a page of release records and corresponding revisions. The "releases" records represent changes in the snap channel map, in other words, which revision is appearing in each channel. Additionally to the releases, each page contains a range of "revisions" involved in the release context, even the unreleased ones. This allows clients to inspect them chronologically (according to the time they were uploaded). Each page (`?page=N`) contains up to 500 (`?size=N`) release records and the number of revisions may vary according to the release profile. Requires a discharged macaroon with ACL_PACKAGE_ACCESS permission. If the release is not progressive, all values in the ``progressive`` dictionary will be ``null``. If progressive, values for ``paused`` and ``percentage`` will not be null, following the data types described in the :ref:`snap-release API endpoint `. ``progressive.current-percentage`` is always null. Changelog _________ * Version 14: Added ``current-percentage`` to the ``progressive`` dict. * Version 13: Added ``status`` to the tracks metadata dict. * Version 12: Added ``title`` and ``publisher`` to the snap metadata dict. * Version 11: Removed the field ``key`` in the ``progressive`` dictionary. * Version 9: Added two new top-level fields to the response: ``tracks``, listing the most relevant tracks for this snap, with proper metadata and ordering; and ``channels``, listing the most relevant channels, including the channel breakdown with ``track``, ``risk`` and ``branch`` and their ``fallback`` channel. Branches are only included in the ``channels`` list if there is a release available in that branch. * Version 8: Added two new fields to the ``releases`` dictionaries: ``channel``, providing the channel name for the release; and ``expiration-date`` that, if not null, indicates when the release will expire, in ISO 8601 format. * Version 6: Added new field ``snap`` to the response including metadata from the snap itself. * Version 4: Added new field ``progressive`` for each release item, providing details about whether that release is a progressive release or not. Response JSON Schema ____________________ .. code-block:: json { "additionalProperties": false, "properties": { "_links": { "additionalProperties": false, "properties": { "first": { "type": "string" }, "last": { "type": "string" }, "next": { "type": "string" }, "prev": { "type": "string" }, "self": { "type": "string" } }, "required": [ "self" ], "type": "object" }, "releases": { "items": { "additionalProperties": false, "properties": { "architecture": { "introduced_at": 1, "type": "string" }, "branch": { "introduced_at": 1, "type": [ "string", "null" ] }, "channel": { "description": "The channel name for this release.", "introduced_at": 8, "type": "string" }, "expiration-date": { "description": "The date when this release expires, in ISO 8601 format. If null, the release does not expire.", "format": "date-time", "introduced_at": 8, "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "introduced_at": 4, "properties": { "current-percentage": { "introduced_at": 14, "type": [ "number", "null" ] }, "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage", "current-percentage" ], "type": "object" }, "revision": { "introduced_at": 1, "type": [ "integer", "null" ] }, "risk": { "introduced_at": 1, "type": "string" }, "track": { "introduced_at": 1, "type": "string" }, "when": { "format": "date-time", "introduced_at": 1, "type": "string" } }, "required": [ "architecture", "branch", "progressive", "revision", "risk", "track", "when" ], "type": "object" }, "minItems": 0, "type": "array" }, "revisions": { "items": { "additionalProperties": false, "properties": { "architectures": { "introduced_at": 1, "items": { "type": "string" }, "minItems": 1, "type": "array" }, "attributes": { "introduced_at": 2, "type": "object" }, "base": { "introduced_at": 1, "type": "string" }, "build_url": { "introduced_at": 1, "type": [ "string", "null" ] }, "confinement": { "enum": [ "strict", "classic", "devmode" ], "introduced_at": 1, "type": "string" }, "created_at": { "format": "date-time", "introduced_at": 1, "type": "string" }, "epoch": { "additionalProperties": false, "introduced_at": 1, "properties": { "read": { "items": { "type": "integer" }, "minItems": 1, "type": "array" }, "write": { "items": { "type": "integer" }, "minItems": 1, "type": "array" } }, "required": [ "read", "write" ], "type": "object" }, "grade": { "enum": [ "stable", "devel" ], "introduced_at": 1, "type": "string" }, "revision": { "introduced_at": 1, "type": "integer" }, "sha3-384": { "introduced_at": 1, "type": "string" }, "size": { "introduced_at": 1, "type": "integer" }, "status": { "enum": [ "Published", "Unpublished", "ManualReviewPending", "NeedsInformation", "AutomaticallyRejected", "Rejected" ], "introduced_at": 1, "type": "string" }, "version": { "introduced_at": 1, "type": "string" } }, "required": [ "architectures", "attributes", "base", "build_url", "confinement", "created_at", "epoch", "grade", "revision", "sha3-384", "size", "status", "version" ], "type": "object" }, "minItems": 0, "type": "array" }, "snap": { "additionalProperties": false, "description": "Metadata about the requested snap.", "introduced_at": 6, "properties": { "channels": { "description": "The list of most relevant channels for this snap. Branches are only included if there is a release for it.", "introduced_at": 9, "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested snap.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "minItems": 1, "type": "array" }, "default-track": { "description": "The default track name for this snap. If no default track is set, this value is null.", "type": [ "string", "null" ] }, "id": { "description": "The snap ID for this snap package.", "type": "string" }, "name": { "description": "The snap package name.", "type": "string" }, "private": { "description": "Whether this snap is private or not.", "type": "boolean" }, "publisher": { "description": "Publisher details for this snap.", "introduced_at": 12, "properties": { "display-name": { "type": "string" }, "id": { "description": "The Account ID for this user.", "type": "string" }, "username": { "type": "string" } }, "type": "object" }, "title": { "description": "The snap title.", "introduced_at": 12, "type": "string" }, "tracks": { "description": "An ordered list of most relevant tracks for this snap.", "introduced_at": 9, "items": { "additionalProperties": false, "description": "An ordered list of tracks and their metadata for this snap.", "properties": { "creation-date": { "description": "The track creation date, in ISO 8601 format. For the \"latest\" track, the creation date is null.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "The track name.", "type": "string" }, "status": { "description": "The status of this track.", "enum": [ "active", "default" ], "introduced_at": 13, "type": "string" }, "version-pattern": { "description": "A Python regex to validate the versions being released to this track. If null, no validation is enforced.", "type": [ "string", "null" ] } }, "required": [ "name", "creation-date", "pattern" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "id", "channels", "default-track", "name", "private", "tracks" ], "type": "object" } }, "required": [ "_links", "releases", "revisions", "snap" ], "type": "object" } .. _api-snap-channel-map: Snap Channel Map ------------------------------------------------------------------- *Introduced in version 10* .. http:GET:: /api/v2/snaps/(?P[\\w-]+)/channel-map Provide the current channel map of releases for the snap. The "channel-map" records represent latest releases in the different channels for the snap. Additionally to the channel map, the result contains the referenced "revisions" involved in the channel-map context. Requires a discharged macaroon with ACL_PACKAGE_ACCESS permission. Changelog _________ * Version 14: Added ``current-percentage`` to the ``progressive`` dict. * Version 13: Added ``status`` to the tracks metadata dict. * Version 12: Added ``title`` and ``publisher`` to the snap metadata dict. * Version 11: Removed the field ``key`` in the ``progressive`` dictionary. Response JSON Schema ____________________ .. code-block:: json { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "architecture": { "type": "string" }, "channel": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "properties": { "current-percentage": { "introduced_at": 14, "type": [ "number", "null" ] }, "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage", "current-percentage" ], "type": "object" }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "architecture", "channel", "expiration-date", "progressive", "revision", "when" ], "type": "object" }, "minItems": 0, "type": "array" }, "revisions": { "items": { "additionalProperties": false, "properties": { "architectures": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "attributes": { "type": "object" }, "base": { "type": "string" }, "build-url": { "type": [ "string", "null" ] }, "confinement": { "enum": [ "strict", "classic", "devmode" ], "type": "string" }, "created-at": { "format": "date-time", "type": "string" }, "epoch": { "additionalProperties": false, "properties": { "read": { "items": { "type": "integer" }, "minItems": 1, "type": [ "array", "null" ] }, "write": { "items": { "type": "integer" }, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "read", "write" ], "type": "object" }, "grade": { "enum": [ "stable", "devel" ], "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "version": { "type": "string" } }, "required": [ "architectures", "attributes", "base", "build-url", "confinement", "created-at", "epoch", "grade", "revision", "sha3-384", "size", "status", "version" ], "type": "object" }, "minItems": 0, "type": "array" }, "snap": { "additionalProperties": false, "description": "Metadata about the requested snap.", "introduced_at": 6, "properties": { "channels": { "description": "The list of most relevant channels for this snap. Branches are only included if there is a release for it.", "introduced_at": 9, "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested snap.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "minItems": 1, "type": "array" }, "default-track": { "description": "The default track name for this snap. If no default track is set, this value is null.", "type": [ "string", "null" ] }, "id": { "description": "The snap ID for this snap package.", "type": "string" }, "name": { "description": "The snap package name.", "type": "string" }, "private": { "description": "Whether this snap is private or not.", "type": "boolean" }, "publisher": { "description": "Publisher details for this snap.", "introduced_at": 12, "properties": { "display-name": { "type": "string" }, "id": { "description": "The Account ID for this user.", "type": "string" }, "username": { "type": "string" } }, "type": "object" }, "title": { "description": "The snap title.", "introduced_at": 12, "type": "string" }, "tracks": { "description": "An ordered list of most relevant tracks for this snap.", "introduced_at": 9, "items": { "additionalProperties": false, "description": "An ordered list of tracks and their metadata for this snap.", "properties": { "creation-date": { "description": "The track creation date, in ISO 8601 format. For the \"latest\" track, the creation date is null.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "The track name.", "type": "string" }, "status": { "description": "The status of this track.", "enum": [ "active", "default" ], "introduced_at": 13, "type": "string" }, "version-pattern": { "description": "A Python regex to validate the versions being released to this track. If null, no validation is enforced.", "type": [ "string", "null" ] } }, "required": [ "name", "creation-date", "pattern" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "id", "channels", "default-track", "name", "private", "tracks" ], "type": "object" } }, "required": [ "channel-map", "revisions", "snap" ], "type": "object" } .. _api-snap-revision: Snap Revisions ------------------------------------------------------------------- *Introduced in version 1* .. http:GET:: /api/v2/snaps/(?P[\\w-]+)/revisions/(?P[^/]+) Retrieve information about a specific snap revision. Requires a discharged macaroon with ACL_PACKAGE_ACCESS permission. .. http:get:: /api/v2/snaps/(name)/revisions/(revision) :reqheader Authorization: macaroon authorization header for a store admin :status 200: success :status 400: malformed revision. :status 401: authentication required :status 404: snap name or revision do not exist or user does not have enough permission to see it :status 500: internal failure, was not possible to fullfil the request Usage _____ As mentioned in earlier in this documention, this endpoint can be exercised using the ``surl`` command as follows: ``surl -s production -e your-email@example.com https://dashboard.snapcraft.io/api/v2/snaps/the-snap-name/revisions/1234`` where ``your-email@example.com`` has to be an existing account with permission to view the snap named ``the-snap-name``. This endpoint allows for two variants: 1- Obtain the revision details for the latest revision. To exercise this, use the special string ``latest`` as the revision value. For example: https://dashboard.snapcraft.io/api/v2/snaps/the-snap-name/revisions/latest 2- Optionally, the content of the snap.yaml for the revision can be requested by passing the query parameter ``include-yaml`` with a true-like value. For example: https://dashboard.snapcraft.io/api/v2/snaps/foo/revisions/latest?include-yaml=1 Example _______ .. include:: ../../examples/requests/snap_revision Errors ______ .. include:: ../../examples/requests/snap_revision_errors Response JSON Schema ____________________ .. code-block:: json { "additionalProperties": false, "properties": { "revision": { "additionalProperties": false, "properties": { "architectures": { "introduced_at": 1, "items": { "type": "string" }, "minItems": 1, "type": "array" }, "attributes": { "introduced_at": 2, "type": "object" }, "base": { "introduced_at": 1, "type": "string" }, "build_url": { "introduced_at": 1, "type": [ "string", "null" ] }, "confinement": { "enum": [ "strict", "classic", "devmode" ], "introduced_at": 1, "type": "string" }, "created_at": { "format": "date-time", "introduced_at": 1, "type": "string" }, "epoch": { "additionalProperties": false, "introduced_at": 1, "properties": { "read": { "items": { "type": "integer" }, "minItems": 1, "type": "array" }, "write": { "items": { "type": "integer" }, "minItems": 1, "type": "array" } }, "required": [ "read", "write" ], "type": "object" }, "grade": { "enum": [ "stable", "devel" ], "introduced_at": 1, "type": "string" }, "revision": { "introduced_at": 1, "type": "integer" }, "sha3-384": { "introduced_at": 1, "type": "string" }, "size": { "introduced_at": 1, "type": "integer" }, "status": { "enum": [ "Published", "Unpublished", "ManualReviewPending", "NeedsInformation", "AutomaticallyRejected", "Rejected" ], "introduced_at": 1, "type": "string" }, "version": { "introduced_at": 1, "type": "string" } }, "required": [ "architectures", "attributes", "base", "build_url", "confinement", "created_at", "epoch", "grade", "revision", "sha3-384", "size", "status", "version" ], "type": "object" } }, "required": [ "revision" ], "type": "object" }