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-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

{
    "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-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

{
    "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

Request Headers:

• Authorization – macaroon authorization header for a declaration reviewer or snap owner

Status Codes:

• 200 OK – success

• 400 Bad Request – error

• 401 Unauthorized – authentication required

• 404 Not Found – snap name does not exist or snap declaration data does not exist or user does not have enough permission

• 500 Internal Server Error – 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

Request Headers:

• Authorization – macaroon authorization header for a declaration reviewer

Status Codes:

• 200 OK – success

• 400 Bad Request – error

• 401 Unauthorized – authentication required

• 404 Not Found – snap name does not exist or user does not have enough permission

• 500 Internal Server Error – 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:

GET /api/v2/snaps/the-snap-name/capabilities
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

{
    "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 information 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:

PUT /api/v2/snaps/the-snap-name/capabilities
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json

{
    "plugs": "{\"network-control\": {\"deny-auto-connection\": \"false\"}, \"test\": {\"deny-auto-connection\": \"false\"}}",
    "slots": "{\"slot1\": {}, \"slot2\": {}}",
    "auto_aliases": "[\"foo\", \"bar\"]",
    "aliases_v2": "[{\"name\": \"foo\", \"target\": \"foocmd\"}, {\"name\": \"bar\", \"target\": \"barcmd\"}]",
    "allow_classic_confinement": true,
    "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\"]}]",
    "refresh_control": "[\"foo\", \"bar\", \"bat\"]"
}

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 information 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"
}