Using the REST API
The REST API provides access to snapd’s state and many of its key functions.
See below for details on accessing the API, authentication, JSON elements and error types, and see the API reference for which actions can be performed and which elements can be requested.
Accessing the API
The /run/snapd.socket
UNIX socket is used to connect a client to the API.
To send a POST request with curl, for example, the following will ask snapd to install the hello snap from the edge channel:
sudo curl -sS --unix-socket /run/snapd.socket \
http://localhost/v2/snaps/hello \
-X POST -d '{"action": "install", "channel": "edge"}'
A request will return a JSON-formatted object. The following example uses curl to request the list of installed snaps, piped through jq for formatting:
$ sudo curl -sS --unix-socket /run/snapd.socket http://localhost/v2/apps \
| jq
{
"type": "sync",
"status-code": 200,
"status": "OK",
"result": [
{
"snap": "anbox-installer",
"name": "anbox-installer"
}
]
}
HTTPS connections over a TCP socket are under consideration for a future release.
Authentication
The API incorporates three levels of access:
- open: API requests will succeed without authorisation
- authenticated: requires suitable authorisation to be provided with each request
- root: root user gains authenticated access without sending authorisation
If an app or client is already running as root, it does not require the use of macaroons or any further authentication. The API will by default allow access to anything that needs to be authentication.
Authorisation is provided by sending a Macaroon with the HTTP authorisation header. For example:
Authorization: Macaroon root="serialized-store-macaroon",discharge="discharge-for-macaroon-authentication"
If available, Polkit can also be used for authentication. The client may choose to allow user interaction for authentication, e.g. showing a graphical dialogue. This is done by setting an HTTP header (defaults to false):
X-Allow-Interaction: true
Responses
For each request, the following JSON object is returned:
Example:
{
"type": "sync",
"status-code": 200,
"status": "OK",
"maintenance": {
"kind": "system-restart",
"message": "system is restarting"
}
}
Fields
-
type
: One ofsync
,async
orerror
-
status-code
: HTTP status code matching the HTTP status line -
status
: HTTP reason phrase matching the HTTP status line -
maintenance
: JSON object containing maintenance information (optional)
Maintenance Fields
-
kind
: Kind of maintenance restart, one ofsystem-restart
ordaemon-restart
-
message
: Text to show to user
Synchronous response
For a standard synchronous operation, the following JSON object is returned:
Example:
{
"type": "sync",
"status-code": 200,
"status": "OK",
"result": { "name": "value" },
}
Fields
In addition to the standard response fields, the following can also be present:
-
result
: Result from the request. This can be any JSON structure and is commonly either an object or an array.
Asynchronous Response
When a request takes time to complete, an asynchronous response is returned.
The request is assigned a change id, which can be checked by requesting GET /v2/changes/[id]
.
Example:
{
"type": "async",
"status-code": 202,
"status": "Accepted",
"change": "401",
}
Fields
In addition to the standard response fields the following can be present:
-
change
: identifier for the change in progress
Error response
If a request cannot be completed, an error response is returned.
Example:
{
"type": "error",
"status-code": 401,
"status": "Unauthorized",
"result": {
"message": "access denied",
"kind": "login-required",
}
}
Fields
In addition to the standard response fields the following can be present:
-
result
: Error information
Result Fields
-
message
: Description of the error, suitable for displaying to a user -
kind
: Unique code for the error, to enable a snapd client to display appropriate behaviour (optional) -
value
: extra information on the error, typically a string for the snap name or an object with fields dependent on the kind (optional)
Status codes
The REST API returns standard HTTP error response status ranges and codes, such as 4xx for client errors and 5xx for server side issues, with descriptions. For example:
Code | Status | Example description |
---|---|---|
400 | Bad request | Snap is already installed |
400 | Bad request | Snap is not installed / unknown action |
401 | Unauthorized | Access denied. Login required. |
403 | Forbidden | Access denied. Login required. |
404 | Not found | Channel not available / snap does not exist |
409 | Conflict | Snap snap has change-kind change in progress |
500 | Internal server error | many unexpected errors |
Conflict errors (409) may be temporary. They are often returned when a new operation on an entity cannot be initiated because a previous operation is still in progress. This might cause new operations on one or more snaps to see errors with the snap-change-conflict
error kind, for example. When a conflicting operation completes, new operations may be retried and should later succeed, assuming the completed operation didn’t break any dependent state for the new operation.
Error kinds
The following error kind
values provide extra context on an error response:
-
app-not-found
: the requested app couldn’t be found. -
assertion-not-found
: assertion can not be found. -
auth-cancelled
: authentication was cancelled by the user. -
bad-query
: a bad query was provided. -
dns-failure
: DNS not responding. -
insufficient-disk-space
: returned when disk space awareness is enabled and either an install, remove or refresh operation fails due to insufficient free disk space. The errorvalue
is an object that containssnap-names
, an array of affected snaps, and achange-kind
string with the failed operation. -
interfaces-unchanged
: the requested interfaces’ operation would have no effect. -
invalid-auth-data
: the authentication data provided failed to validate (e.g. a malformed email address). Thevalue
of the error is an object with a key per failed field and a list of the failures on each field. -
login-required
: the requested operation cannot be performed without an authenticated user. This is the kind of any other 401 Unauthorized response. -
network-timeout
: a timeout occurred during the request. -
option-not-found
: the given configuration option does not exist. -
password-policy
: provided password doesn’t meet system policy. -
snap-already-installed
: the requested snap is already installed. -
snap-architecture-not-available
: no snap revision on specified architecture. Value has the same format as forsnap-channel-not-available
. -
snap-change-conflict
: the requested operation would conflict with currently ongoing change. This is a temporary error. The errorvalue
is an object with optional fieldssnap-name
,change-kind
of the ongoing change. -
snap-channel-not-available
: no snap revision on specified channel. Thevalue
of the error is a rich object with requestedsnap-name
,action
,channel
,architecture
, and actually availablereleases
as list of{"architecture":... , "channel": ...}
objects. -
snap-local
: cannot perform operation on local snap. -
snap-needs-classic
: the requested snap needs classic confinement to be installed. -
snap-needs-classic-system
: the requested snap can’t be installed on the current non-classic system. -
snap-needs-devmode
: the requested snap needs devmode to be installed. -
snap-no-update-available
: the requested snap does not have an update available. -
snap-not-a-snap
: the given snap or directory does not look like a snap. -
snap-not-classic
: snap not compatible with classic mode. -
snap-not-found
: the requested snap couldn’t be found. -
snap-not-installed
: the requested snap is not installed. -
snap-revision-not-available
: no snap revision available as specified. -
two-factor-failed
: the OTP provided wasn’t recognised. -
two-factor-required
: the client needs to retry thelogin
command including an OTP. -
unsuccessful
: snapctl command was unsuccessful.
Maintenance error kinds
These are used only inside the maintenance
field of responses.
-
daemon-restart
: daemon is restarting. -
system-restart
: system is restarting.
Last updated a month ago.