Using the REST API

doc
1

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

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

:information_source: 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)
1 Like
3

A useful tip. If anyone is playing with the API from the command line, try installing the http snap, which knows about snapd:// schema. Then the following commands will work:

$ http snapd:///v2/connections
$ http snapd:///v2/snaps
$ http snapd:///v2/snaps/lxd

Unfortunately the POST method isn’t as convenient, and may require extra hacks when passing complex JSON objects such as arrays in the request. For simple POST requests it works just as easily as GET. For instance requesting a snap refresh from a channel:

$ http POST snapd:///v2/snaps/lxd action=refresh channel=beta

Note:

  • you may need to use snap run http if there is a httpie package installed in your system and appears earlier in the $PATH
  • you can use sudo http snapd:///v2/.. to access endpoints that would otherwise require authentication
2 Likes
4

Any link to “macaroons”? Where do I find them or how do I determine them?

5

I incorrectly assumed that whenever the endpoint was specified as authenticated, X-Allow-Interaction would result in a Polkit prompt.

The document does says if available, but without any indication of whether it is available in https://snapcraft.io/docs/snapd-api, I can only find it out by actually trying it? Shouldn’t the information “this endpoint supports Polkit authentication” be in the documentation?

6

Typo:

… anything that needs to be authenticated.

… anything that needs authentication.

7

Thank you for letting me know - now fixed!