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
• Authentication
• General response
  • synchronous responses
  • asynchronous responses

---

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

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

sudo curl -sS --unix-socket /run/snapd.socket \
http://localhost/v2/quotas \
-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 8 months ago.