Overrides API

The Overrides API supports two operations: list overrides, and set overrides.

All operations require an “Authorisation” header, as described in API authentication.

List overrides

To list overrides for a snap name, perform a GET request to /v2/metadata/overrides/{snap_name}:

Example: to list overrides for snap_a:

Request:

GET /v2/metadata/overrides/snap_a HTTP/1.1
Host: <store domain>
Accept: application/json
X-Ubuntu-Series: 16

Note the X-Ubuntu-Series header.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
...

{
    "overrides": [
        {
            "snap_id": ...,
            "snap_name": "snap_a",
            "revision": 20,
            "upstream_revision": 23,
            "channel": "stable",
            "architecture": "x86",
            "series": "16"
        }
    ]
}

The JSON Schema for the response document is:

{
    "type": "object",
    "properties": {
        "overrides": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "snap_id": {"type": "string"},
                    "snap_name": {"type": "string"},
                    "revision": {
                        "type": "integer",
                        "minimum": 1,
                    },
                    "upstream_revision": {
                        "type": ["integer", "null"],
                        "minimum": 1,
                    },
                    "channel": {"type": "string"},
                    "architecture": {"type": "string"},
                    "series": {"type": "string"},
                },
                "required": [
                    "snap_id", "snap_name", "revision", "upstream_revision",
                    "channel", "architecture", "series",
                ],
                "additionalProperties": False,
            },
        },
    },
    "required": ["overrides"],
    "additionalProperties": False,
}

Set overrides

To set overrides, perform a POST request to /v2/metadata/overrides.

Example: override snap_a to revision 20 on the stable channel, and remove any overrides for snap_b on the candidate channel.

Request:

POST /v2/metadata/overrides HTTP/1.1
Host: <store domain>
Accept: application/json
Content-Type: application/json

[
    {
        "snap_name": "snap_a",
        "revision": 20,
        "channel": "stable",
        "series": "16"
    },
    {
        "snap_name": "snap_b",
        "revision": null,
        "channel": "candidate",
        "series": "16"
    }
]

Response:

HTTP/1.1 200 OK
Content-Type: application/json
...

{
    "overrides": [
        {
            "snap_id": ...,
            "snap_name": "snap_a",
            "revision": 20,
            "upstream_revision": 23,
            "channel": "stable",
            "architecture": "x86",
            "series": "16"
        }, {
            "snap_id": ...,
            "snap_name": "snap_b",
            "revision": null,
            "upstream_revision": 13,
            "channel": "candidate",
            "architecture": "x86",
            "series": "16"
        }
    ]
}

The request body format should match the following JSON schema.

{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "snap_name": {"type": "string"},
            "revision": {
                "type": ["integer", "null"],
                "minimum": 1,
            },
            "channel": {"type": "string"},
            "series": {"type": "string"},
        },
        "required": ["snap_name", "revision", "channel", "series"],
        "additionalProperties": False,
    },
    "minItems": 1,
}

To delete an override, simply set its revision field to null. The “series” field must be set to “16” currently.

The response includes the results of the operation. The response format is the same as for listing overrides, except that “revision” can be null if an override was deleted.