Snaps¶
Introduction¶
No introduction documentation yet.
Snap Releases¶
Introduced in version 1
- GET /api/v2/snaps/(?P<name>[\\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
snap-release API endpoint.
progressive.current-percentage is always null.
Changelog¶
Version 14: Added
current-percentageto theprogressivedict.Version 13: Added
statusto the tracks metadata dict.Version 12: Added
titleandpublisherto the snap metadata dict.Version 11: Removed the field
keyin theprogressivedictionary.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; andchannels, listing the most relevant channels, including the channel breakdown withtrack,riskandbranchand theirfallbackchannel. Branches are only included in thechannelslist if there is a release available in that branch.Version 8: Added two new fields to the
releasesdictionaries:channel, providing the channel name for the release; andexpiration-datethat, if not null, indicates when the release will expire, in ISO 8601 format.Version 6: Added new field
snapto the response including metadata from the snap itself.Version 4: Added new field
progressivefor each release item, providing details about whether that release is a progressive release or not.
Response JSON Schema¶
{
"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"
}
Snap Channel Map¶
Introduced in version 10
- GET /api/v2/snaps/(?P<name>[\\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-percentageto theprogressivedict.Version 13: Added
statusto the tracks metadata dict.Version 12: Added
titleandpublisherto the snap metadata dict.Version 11: Removed the field
keyin theprogressivedictionary.
Response JSON Schema¶
{
"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"
}
Snap Revisions¶
Introduced in version 1
- GET /api/v2/snaps/(?P<name>[\\w-]+)/revisions/(?P<revision>[^/]+)¶
Retrieve information about a specific snap revision.
Requires a discharged macaroon with ACL_PACKAGE_ACCESS permission.
- GET /api/v2/snaps/(name)/revisions/(revision)¶
- Request Headers
Authorization – macaroon authorization header for a store admin
- Status Codes
200 OK – success
400 Bad Request – malformed revision.
401 Unauthorized – authentication required
404 Not Found – snap name or revision do not exist or user does not have enough permission to see it
500 Internal Server Error – 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¶
Retrieve information about revision 123 of snap surl
Request:
GET /api/v2/snaps/surl/revisions/123 HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"revision": {
"status": "Published",
"version": "0.4",
"grade": "stable",
"sha3-384": "d53e1c8a66cb03a99aed76f03c49c55ec6110e33c8cb4a12fb2c8715c9349a29321e877483a7bc7718fe552f2533397d",
"build_url": null,
"base": null,
"architectures": [
"amd64"
],
"size": 10969088,
"created_at": "2018-04-13T14:50:02Z",
"epoch": {
"read": null,
"write": null
},
"confinement": "strict",
"revision": 123
}
}
Errors¶
If the requested snap or revision do not exist, or the authenticated user does not have enough permissions to manage such store, the following error response is returned:
Request:
GET /api/v2/snaps/other-snap/revisions/1234 HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
Response:
HTTP/1.1 404 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"code": "resource-not-found",
"message": "The resource requested does not exist or credentials are not sufficient to access it."
}
]
}
If the snap exists but the revision requested is not an integer:
Request:
GET /api/v2/snaps/the-snap/revisions/foo HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"code": "bad-request",
"extra": {
"invalid": "foo"
},
"message": "Revision must be an integer",
}
]
}
If the request could not be fulfilled by any internal error:
Request:
GET /api/v2/snaps/the-snap/revisions/foo HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
Response:
HTTP/1.1 500 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"code": "internal-server-error"
"message": "There was an internal error, please try again later.",
}
]
}
Response JSON Schema¶
{
"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"
}