Using the REST API | Snapcraft documentation

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.

When experimenting the API on a Ubuntu Core system with a connected system user using a dangerous grade image, the curl snap must be installed with the devmode flag to access the UNIX socket.

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 \
-H "Content-Type: application/json" \
-X POST  -d '{"action": "install", "channel": "edge"}'

Similarly, the following curl command will remove a Quota group called allquotas:

sudo curl -sS --unix-socket /run/snapd.socket \
http://localhost/v2/quotas \
-H "Content-Type: application/json" \
-X POST -d '{"action": "remove", "group-name": "allquotas"}'

A request will return a JSON-formatted object. The following example uses curl to GET 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 authenticated.

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 of sync, async or error
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 of system-restart or daemon-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)

Last updated 5 months ago.

Help improve this document in the forum.