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"
}
Snap source workflow¶
Introduced in version 33
- POST /api/v2/snaps/(?P<name>[\\w-]+)/source-workflow¶
Manage snap’s source workflow.
Currently restricted to use only via the source handling machinery.
Request JSON Schema¶
{
"additionalProperties": false,
"properties": {
"source-workflow": {
"additionalProperties": false,
"properties": {
"enabled": {
"enum": [
true
]
}
},
"required": [
"enabled"
],
"type": "object"
}
},
"required": [
"source-workflow"
],
"type": "object"
}
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"source-workflow": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": [
"enabled"
],
"type": "object"
}
},
"required": [
"source-workflow"
],
"type": "object"
}
Snap Capabilities¶
Introduced in version 33
- GET /api/v2/snaps/(?P<name>[\\w-]+)/capabilities¶
- PUT /api/v2/snaps/(?P<name>[\\w-]+)/capabilities¶
Managing the capabilities of snaps in a brand store.
In order to manage the snap declaration in a brand store, a declaration
reviewer or snap owner can GET to the endpoint
/api/v2/snaps/(snap-name)/capabilities, to get the snap capability information.
In order to manage the snap declaration in a brand store, a declaration reviewer can
PUT the endpoint /api/v2/snaps/(snap-name)/capabilities, to update snap’s
capabilities.
Requires a discharged macaroon with ACL_PACKAGE_ACCESS permission.
GET¶
For retrieving the snap’s capabilities with name the-snap-name:
- GET /api/v2/snaps/(the-snap-name)/capabilities¶
- reqheader Authorization
macaroon authorization header for a declaration reviewer
or snap owner
- status 200
success
- status 400
error
- status 401
authentication required
- status 404
snap name does not exist or snap declaration data does not exist or user does not have enough permission
- status 500
internal failure, was not possible to fullfil the request
PUT¶
For updating a snap’s capability information with the snap name the-snap-name:
- PUT /api/v2/snaps/(the-snap-name)/capabilities¶
- reqheader Authorization
macaroon authorization header for a declaration reviewer
- status 200
success
- status 400
error
- status 401
authentication required
- status 404
snap name does not exist or user does not have enough permission
- status 500
internal failure, was not possible to fullfil the request
Usage¶
As mentioned earlier in this documentation, 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/capabilities
where your-email@example.com has to be an existing account with
permission to view the snap named the-snap-name.
Example¶
Get the snap’s capability information with the snap-name. The snap owner, collaborators, store admin/reviewers/viewers and snap declaration reviewers can access the snap’s capability information.
Request:
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"snap_id": "MUXqSUCLn4QqtWmtY622hGV3BseW6AHj",
"publisher": {
"email": "email-cncER@example.com",
"username": "user-ZtKI1"
},
"snap_name": "test-package",
"snap_url": "/snaps/pkg-1/",
"store_name": "Store Name dtfaz",
"store_id": "store-dtfaz",
"is_private": false,
"created_timestamp": "2017-06-06T00:00:00",
"state": "Approved",
"snap_yaml_raw": "name: test-package\n",
"latest_revision": 1,
"scope": null,
"enable_scoped_rules": false,
"aliases_v2": [
{"name": "foo", "target": "foocmd"},
{"name": "bar", "target": "barcmd"}
],
"auto_aliases": ["foo", "bar"],
"refresh_control": ["foo", "bar", "bat"],
"revision_authority": [
{
"account-id": "acc1",
"provenance": ["provenance1", "provenance2"]
},
{
"account-id": "acc2",
"provenance": ["provenance2"],
"on-store": ["storeid"],
"on-brand": ["brandname1"],
"on-model": ["brandname1/modelname1"],
"min-revision": "100",
"max-revision": "100000"
}
],
"plugs": {
"plug-interface": {
"auto-connect": "true"
}
},
"slots": {
"slot-interface": {
"auto-connect": "false"
}
},
"has_existing_revisions": true,
"allow_classic_confinement": true
}
Update the capabilities infromation of the snap. The declaration reviewer can update plugs, slots, auto_aliases, aliases_v2, allow_classic_confinement, revision_authority and refresh_control fields. The owner can update only plugs or slots fields with specific values. For example a plug entry should be a pre-defined entry and its value can be updated from true to false.
Request:
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"snap_id": "JjQklCksRgxRkO5Z8HYHmJEP0l8y9zvN",
"publisher": {
"email": "email-7Bf9N@example.com",
"username": "user-KeITK"
},
"snap_name": "test-package",
"snap_url": "/snaps/pkg-1/",
"store_name": "Store Name ndqd2",
"store_id": "store-ndqd2",
"is_private": false,
"created_timestamp": "2017-06-06T00:00:00",
"state": "Approved",
"snap_yaml_raw": "name: test-package\n",
"latest_revision": 1,
"scope": null,
"enable_scoped_rules": false,
"aliases_v2": [
{
"name": "foo",
"target": "foocmd"
},
{
"name": "bar",
"target": "barcmd"
}
],
"auto_aliases": [
"foo",
"bar"
],
"refresh_control": [
"foo",
"bar",
"bat"
],
"revision_authority": [
{
"account-id": "account-1",
"provenance": [
"provenance-1"
]
},
{
"account-id": "account-2",
"provenance": [
"provenance-2",
"p3"
],
"min-revision": "10",
"max-revision": "20",
"on-store": [
"s1",
"s2"
],
"on-brand": [
"b1",
"b2"
],
"on-model": [
"b1/mx",
"b2/mx"
]
}
],
"plugs": {
"network-control": {
"deny-auto-connection": "false"
},
"test": {
"deny-auto-connection": "false"
}
},
"slots": {
"slot1": {},
"slot2": {}
},
"has_existing_revisions": true,
"allow_classic_confinement": true
}
Errors¶
If the given snap name does 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/the-snap-name/capabilities 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’s capabilities information does not exist, the following error response is returned:
Request:
GET /api/v2/snaps/the-snap-name/capabilities 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."
}
]
}
When updating, if the aliases v2 field in the body is not a JSON list of name and target, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
'aliases_v2': [
{'name': 'foo', 'test': 'foocmd'},
{'name': 'bar', 'target': 'barcmd'},
]
}
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "Aliases (v2) must be a json-serialized list of maps with 'name' and 'target' string entries.",
"code": null,
"extra": {"field": "aliases_v2"}
},
]
}
If the revision authority map field in the body is not a JSON list; ‘account-id’, ‘provenance’ does not exist in each entry; an entry that is other than ‘max-revision’, ‘min-revision’, ‘on-store’, ‘on-brand’, ‘on-model’ exist on the entries; the ‘account-id’ field is not a string; the ‘provenance’, ‘on-store’, ‘on-brand’ and ‘on-model’ fields are not lists of strings; ‘min-revision’ and ‘max-revision’ are not strings, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
'revision_authority': [
{'account-id': 'account-1'},
]
}
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "Revision-authority must be a json-serialized list of maps with mandatory 'account-id' string entry, mandatory 'provenance' list of strings entry, optional 'on-store', 'on-brand', 'on-model' list of strings entries,
and optional 'min-revision' and 'max-revision' string entries.",
"code": null,
"extra": {"field": "revision_authority"}
}
]
}
If the plug or slots fields in the body are not a JSON serialized dict with string scalar values, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
"plugs": {
"network-control": {
"deny-auto-connection": 3,
},
"test": {
"deny-auto-connection": "false"
}
}
}
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "Plugs must be a json-serialized dict. Dicts and lists are allowed as values, scalar values must be strings.",
"code": null,
"extra": {"field": "plugs"}
}
]
}
If the auto aliases field is not a list of strings and string values must be declared in the aliases v2 field’s name value, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
'auto_aliases': ['foo', 'bar', {'test': 'test'}],
'aliases_v2': [
{'name': 'foo', 'target': 'foocmd'},
{'name': 'bar', 'target': 'barcmd'},
]
}
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "Auto-aliases must be a json-serialized list of strings.",
"code": null,
"extra": {"field": "auto_aliases"}
},
{
"message": "During the transition phase if either aliases (v2) or auto-aliases are set they must both declare the same alias names.",
"code": null
}
]
}
If the refresh control field is not list of strings, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
'refresh_control': ['foo', 'bar', 'bat', {'test':'test'}],
}
Response:
HTTP/1.1 400 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "Refresh-control must be a json-serialized list of strings.",
"code": null,
"extra": {"field": "refresh_control"}
}
]
}
If the user is not a declaration reviewer but they can review the package and an entry other than plugs and slots entered, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
"plugs": {
"network-control": {
"allow-connection": "false"
},
},
"refresh_control": ['foo'],
}
Response:
HTTP/1.1 404 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "The resource requested does not exist or credentials are not sufficient to access it.",
"code": "resource-not-found"
}
]
}
If the user is not a declaration reviewer but they can review the package and the data in the body includes plugs or slots data that the user does not allowed to change, the following error response is returned:
Request:
PUT /api/v2/snaps/the-snap-name/capabilities HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json
{
"plugs": {
"test": {
"deny-auto-connection": "false"
}
}
}
Response:
HTTP/1.1 404 OK
Content-Type: application/json; charset=utf-8
{
"error-list": [
{
"message": "The resource requested does not exist or credentials are not sufficient to access it.",
"code": "resource-not-found"
}
]
}
Request JSON Schema¶
{
"additionalProperties": false,
"properties": {
"aliases_v2": {
"type": [
"string",
"null"
]
},
"allow_classic_confinement": {
"type": [
"boolean",
"null"
]
},
"auto_aliases": {
"type": [
"string",
"null"
]
},
"plugs": {
"type": [
"string",
"null"
]
},
"refresh_control": {
"type": [
"string",
"null"
]
},
"revision_authority": {
"type": [
"string",
"null"
]
},
"slots": {
"type": [
"string",
"null"
]
}
},
"type": "object"
}
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"aliases_v2": {
"type": [
"object",
"null"
]
},
"allow_classic_confinement": {
"type": [
"boolean",
"null"
]
},
"auto_aliases": {
"type": [
"string",
"null"
]
},
"created_timestamp": {
"description": "The date when the snap package is created.",
"format": "date-time",
"type": "string"
},
"enable_scoped_rules": {
"description": "If enabled, declaration plugs/slots rules will be scoped for the scope.",
"type": "boolean"
},
"has_existing_revisions": {
"description": "It will be set if snap has any upload.",
"type": "boolean"
},
"is_private": {
"description": "Indicate whether this snap is visible in public lists.",
"type": "boolean"
},
"latest_revision": {
"description": "The latest revision number of the snap package.",
"type": [
"string",
"null"
]
},
"plugs": {
"type": [
"string",
"null"
]
},
"publisher": {
"description": "The publisher infromation of the snap package.",
"properties": {
"email": {
"type": "string"
},
"username": {
"type": "string"
}
},
"type": "object"
},
"refresh_control": {
"type": [
"string",
"null"
]
},
"revision_authority": {
"type": [
"object",
"null"
]
},
"scope": {
"description": "The declaration scope of the store.",
"type": [
"object",
"null"
]
},
"slots": {
"type": [
"string",
"null"
]
},
"snap_id": {
"description": "The snap ID for this snap package.",
"type": "string"
},
"snap_name": {
"description": "The name of the snap package.",
"type": "string"
},
"snap_url": {
"description": "The absolute URL of the snap package.",
"type": [
"string",
"null"
]
},
"snap_yaml_raw": {
"description": "The manifest of the snap package.",
"type": [
"string",
"null"
]
},
"state": {
"description": "The state of the snap package.",
"type": "string"
},
"store_id": {
"description": "ID of the brand store that the snap package is released.",
"type": "string"
},
"store_name": {
"description": "Name of the brand store that the snap package is released.",
"type": "string"
}
},
"required": [
"snap_id",
"publisher",
"snap_name",
"snap_url",
"store_name",
"store_id",
"is_private",
"created_timestamp",
"state",
"snap_yaml_raw",
"latest_revision",
"scope",
"enable_scoped_rules",
"aliases_v2",
"auto_aliases",
"refresh_control",
"revision_authority",
"plugs",
"slots",
"has_existing_revisions"
],
"type": "object"
}