Search

V2 APIs

All the documentation for V2 Search is with its definition snaps_find.

V1 APIs

All the V1 endpoints under the "search" group share the same output schema:

{
  "_embedded": {
    "clickindex:package": [
      {<snap representation>},
      ...
    ]
  }
}

The <snap representation>, as the name suggests, is a JSON object representing a snap revision released to a specific channel, with the following default fields:

  • aliases
  • anon_download_url: (deprecated) user download_url
  • apps
  • architecture
  • base
  • binary_filesize
  • channel
  • common_ids
  • confinement
  • contact
  • content: (deprecated) obsolete information
  • date_published
  • description
  • developer_id
  • developer_name
  • developer_validation
  • download_sha3_384
  • download_sha512: (deprecated) use download_sha3_384
  • download_url
  • epoch
  • gated_snap_ids
  • icon_url: (deprecated) use media
  • last_updated
  • license
  • name: (deprecated) use package_name
  • origin:
  • package_name
  • prices
  • private
  • publisher: (deprecated) use developer_name
  • ratings_average (deprecated) obsolete information
  • release
  • revision
  • screenshot_urls: (deprecated) use media
  • snap_id
  • summary
  • support_url
  • title
  • version
  • website

Additional fields have to be explicitly requested:

  • channel_maps_list
  • media
  • sections
  • snap_yaml_raw

We strongly recommend clients to specify the required fields explicitly to avoid unexpected compatibility breakages by changes in the default set, e.g.:

GET /api/v1/search?q=magic&fields=package_name,revision,architecture,channel

Introduced in version 1

Summary: GET /api/v1/snaps/search

Search public snaps in the Store.

The endpoint supports the following optional query string parameters:

  • q: the search term to be matched (fulltext search) across snaps on name, title, keywords, summary and description
  • scope: if specified as 'wide' snaps released on any risk of the 'latest' track will be returned, otherwise only the ones released to 'stable'
  • arch: if specified as 'wide' matching snaps released on any architecture will be returned, otherwise only the ones matching the X-Ubuntu-Architecture header (defaults to 'amd64')
  • confinement: comma-separated list of confinements restricting the results (defaults to 'strict,classic')
  • promoted: if specified as 'true', restricts the results to snaps that are assigned to at least one section
  • section: if specified as the name of an existing section (see section_listing endpoint for the list of sections) without a search_term it lists the featured snaps within the given section, with search_term it returns the matching snaps within the given section.
  • exclude_non_free: if specified as 'true' it will restrict the results to snaps with free licences (see SPDX 2.0 definition)
  • private: if specified as 'true' it will restrict the results to private snaps to which the principal (requires Authorization header) has access
  • common_id: if specified it will match only snaps including the given application ID (exact-matching).
  • page_size: number of results per page, defaults to 100 and is limited to 250 entries
  • page: results page, the results _links field contains HAL-navigation links to first, previous, self, next and last pages

snap_search changelog

  • Version 3: Added 'arch' query string parameter.

  • Version 2: Added 'scope' query string parameter.

section_listing

Introduced in version 1

Summary: GET /api/v1/snaps/sections

No documentation yet.

store_snaps

Introduced in version 1

Summary: GET /api/v1/snaps

List snaps from a store.

This endpoint lists all snaps currently released to the stable channel in the context store. The output schema is the same used by snap_searches:

This endpoint requires the following headers:

  • X-Ubuntu-Series: currently "16"
  • X-Ubuntu-Store: the context store ID, subjected to further authentication

Setting the `X-Ubuntu-Architecture' to a specific architecture name ('amd64', 'i386', 'armhf', etc) will filter out snaps not released in that architecture.

The results can be further filtered by the following query-string parameters:

  • channel: lists only results released to a specific channel ([<track>/]<risk>[/<branch>] notation)

snap_names

Introduced in version 1

Summary: GET /api/v1/snaps/names

List public and stable snap names for a given store, arch and series.

snaps_find

Introduced in version 19

Summary: GET /v2/snaps/find

Find snaps.

The current implementation of V2 Search is limited to the requirements of snapd but it is intended to eventually replace the older V1 Search APIs completely.

Results are limited to a maximum of 100 snaps.

Headers

  • Authorization: Publisher macaroon. Required to search private snaps.
  • Snap-Device-Authorization: Required for access to restricted stores.
  • Snap-Device-Series: Required. Must have the value "16".
  • Snap-Device-Store: Store to search. Defaults to "ubuntu".

Query Parameters

  • q=string: Full text query.
  • fields=comma separated list: See Supported Fields.
  • name-startswith=string: Filter name by starts with prefix.
  • architecture=string: Filter by architecture.
  • common-id=string: Filter for snaps containing this common_id.
  • category=string: Filter by category membership.
  • channel=string: Filter by channel.
  • confinement=comma separated list: Filter by confinement type. Defaults to strict,classic
  • featured=true/false: Filter by featured in category. Defaults is to return both featured and not featured snaps.
  • private=true/false: Filter only private snaps. Default is false, public snaps only.

Supported Fields

Only the name and snap-id are returned unless fields are specified.

If the relevant fields are selected the revision in the response is picked using the "most stable" algorithm.

  • base
  • categories
  • channel
  • common-ids
  • confinement
  • contact
  • description
  • download
  • license
  • media
  • prices
  • private
  • publisher
  • revision
  • store-url
  • summary
  • title
  • type
  • version
  • website

snaps_find changelog

  • Version 20: Added common-ids, store-url and website

  • Version 19: Add new V2 Search API

Response JSON Schema

{
    "additionalProperties": false,
    "properties": {
        "error-list": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "message"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "results": {
            "items": {
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "revision": {
                        "additionalProperties": false,
                        "properties": {
                            "base": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "channel": {
                                "type": "string"
                            },
                            "common-ids": {
                                "introduced_at": 20,
                                "items": {
                                    "type": "string"
                                },
                                "type": "array"
                            },
                            "confinement": {
                                "type": "string"
                            },
                            "download": {
                                "additionalProperties": false,
                                "properties": {
                                    "size": {
                                        "type": "number"
                                    }
                                },
                                "required": [
                                    "size"
                                ],
                                "type": "object"
                            },
                            "revision": {
                                "type": "number"
                            },
                            "type": {
                                "type": "string"
                            },
                            "version": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "snap": {
                        "additionalProperties": false,
                        "properties": {
                            "categories": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "featured": {
                                            "type": "boolean"
                                        },
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "name",
                                        "featured"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "contact": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string"
                            },
                            "license": {
                                "type": "string"
                            },
                            "media": {
                                "items": {
                                    "additionalProperties": false,
                                    "properties": {
                                        "height": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        },
                                        "type": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        },
                                        "width": {
                                            "type": [
                                                "null",
                                                "integer"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "type",
                                        "url",
                                        "width",
                                        "height"
                                    ],
                                    "type": "object"
                                },
                                "type": "array"
                            },
                            "prices": {
                                "type": "object"
                            },
                            "private": {
                                "type": "boolean"
                            },
                            "publisher": {
                                "additionalProperties": false,
                                "properties": {
                                    "display-name": {
                                        "type": "string"
                                    },
                                    "id": {
                                        "type": "string"
                                    },
                                    "username": {
                                        "type": "string"
                                    },
                                    "validation": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "id",
                                    "username",
                                    "display-name"
                                ],
                                "type": "object"
                            },
                            "store-url": {
                                "introduced_at": 20,
                                "type": "string"
                            },
                            "summary": {
                                "type": "string"
                            },
                            "title": {
                                "type": "string"
                            },
                            "website": {
                                "introduced_at": 20,
                                "type": [
                                    "null",
                                    "string"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "snap-id": {
                        "type": "string"
                    }
                },
                "required": [
                    "name",
                    "snap-id",
                    "snap"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "results"
    ],
    "type": "object"
}

legacy_search (DEPRECATED)

Deprecated: Deprecated from version 1

Summary: GET /api/v1/search

Legacy search implementation.

Ignore ':' in the query string for the sake of simplicity and match on exact snap name.

Response is wrapped into the usual CPI '_embedded["clickindex:package"]' structure.

TODO: field whitelist support.

Since the search could perform badly and is deprecated, we check that the useragent calling is actually a snapd process, based on the User-Agent.

© 2019 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.