Confdb Schemas¶

Introduction¶

The Confdb Schemas API enables confdb-schema assertions management.

All endpoints require a macaroon authenticated request with no special permissions.

See Macaroons for details on how to obtain a suitable macaroon for interacting with this API. You could also use the surl command line, available as a snap:

snap install surl

to exercise this (and other) store APIs. The following example authenticates to the store and saves the macaroon locally for use in subsequent requests:

surl -a prod -s production -e <email> [[-p <macaroon_permission>]]

surl -a prod -X <http-method> https://dashboard.snapcraft.io/<endpoint> [[-d '<json payload>']]

See surl help for the details about these and other surl options.

The Confdb Schemas API is exposed at the following base URLs:

Staging: https://dashboard.staging.snapcraft.io/api/v2/confdb-schemas
Production: https://dashboard.snapcraft.io/api/v2/confdb-schemas

Response Format¶

JSON will be returned in all responses from the API, including error responses, please refer to the following section for details about the format.

Prepare confdb-schema assertion headers ready for signing.¶

Introduced in version 16

POST /api/v2/confdb-schemas/build-assertion¶

Prepare confdb-schema headers for local signing.

Return confdb-schema assertion headers ready for local signing by the publisher.

reqheader Authorization:: macaroon authorization header for an active user
status 200:: success
status 400:: error
status 401:: authentication required

Usage¶

As mentioned in the introduction, this endpoint can be exercised using the surl command as follows:

surl -s production -e your-email@example.com -X POST https://dashboard.snapcraft.io/api/v2/confdb-schemas/build-assertion -d '<input-data-as-json>'

where your-email@example.com has to be an existing account.

Example¶

Prepare assertion headers for a confdb-schema named “network”.

Request:

POST /api/v2/confdb-schemas/build-assertion HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json

{
    "account-id": "f22PSauKuNkwQTM9Wz67ZCjNACuSjjhN",
    "name": "network",
    "views": {
        "wifi-setup": {
            "rules": [
                {"request": "ssids", "storage": "wifi.ssids"},
                {"request": "ssid", "storage": "wifi.ssid", "access": "read-write"},
                {"request": "password", "storage": "wifi.psk", "access": "write"},
                {"request": "status", "storage": "wifi.status", "access": "read"},
                {"request": "private.{placeholder}", "storage": "wifi.{placeholder}"}
            ]
        }
    },
    "body": "{\n  \"storage\": {\n    \"schema\": {\n      \"wifi\": {\n        \"values\": \"any\"\n      }\n    }\n  }\n}",
    "timestamp": "2024-03-06T09:00:00Z"
}

Response:

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

{
    "type": "confdb-schema",
    "account-id": "f22PSauKuNkwQTM9Wz67ZCjNACuSjjhN",
    "authority-id": "f22PSauKuNkwQTM9Wz67ZCjNACuSjjhN",
    "name": "network",
    "revision": "0",
    "views": {
        "wifi-setup": {
            "rules": [
                {"request": "ssids", "storage": "wifi.ssids"},
                {"request": "ssid", "storage": "wifi.ssid", "access": "read-write"},
                {"request": "password", "storage": "wifi.psk", "access": "write"},
                {"request": "status", "storage": "wifi.status", "access": "read"},
                {"request": "private.{placeholder}", "storage": "wifi.{placeholder}"}
            ]
        }
    },
    "body": "{\n  \"storage\": {\n    \"schema\": {\n      \"wifi\": {\n        \"values\": \"any\"\n      }\n    }\n  }\n}",
    "timestamp": "2024-03-06T09:00:00Z"
}

Errors¶

Request payload contains a number of request JSON schema violations.

Request:

POST /api/v2/confdb-schemas/build-assertion HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/json

{
    "surprise-field": 123,
    "name": "name",
    "views": [
        "wifi-setup": {
            "rules": [
                {"request": "ssids", "storage": "wifi.ssids"},
                {"request": "ssid", "storage": "wifi.ssid", "access": "read-write"},
                {"request": "password", "storage": "wifi.psk", "access": "write"},
                {"request": "status", "storage": "wifi.status", "access": "read"},
                {"request": "private.{placeholder}", "storage": "wifi.{placeholder}"}
            ]
        }
    ],
    "body": ""
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error-list": [
        {
            "message": "Additional properties are not allowed ('surprise-field' was unexpected) at /",
            "code": "invalid-request"
        },
        {
            "message": "'account-id' is a required property at /",
            "code": "invalid-request"
        }
    ]
}

Request JSON Schema¶

{
    "additionalProperties": false,
    "definitions": {
        "ContentRule": {
            "additionalProperties": false,
            "properties": {
                "access": {
                    "enum": [
                        "read",
                        "write",
                        "read-write"
                    ]
                },
                "content": {
                    "items": {
                        "oneOf": [
                            {
                                "$ref": "#/definitions/Rule"
                            },
                            {
                                "$ref": "#/definitions/ContentRule"
                            }
                        ]
                    },
                    "minItems": 1,
                    "type": "array"
                },
                "request": {
                    "minLength": 1,
                    "type": "string"
                },
                "storage": {
                    "minLength": 1,
                    "type": "string"
                }
            },
            "required": [
                "storage",
                "content"
            ],
            "type": "object"
        },
        "Rule": {
            "additionalProperties": false,
            "properties": {
                "access": {
                    "enum": [
                        "read",
                        "write",
                        "read-write"
                    ]
                },
                "request": {
                    "minLength": 1,
                    "type": "string"
                },
                "storage": {
                    "minLength": 1,
                    "type": "string"
                }
            },
            "required": [
                "storage"
            ],
            "type": "object"
        }
    },
    "properties": {
        "account-id": {
            "description": "Issuer of the confdb-schema assertion",
            "minLength": 1,
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "name": {
            "description": "Confdb-schema name",
            "minLength": 1,
            "type": "string"
        },
        "summary": {
            "type": "string"
        },
        "views": {
            "additionalProperties": false,
            "description": "Views in a confdb-schema assertion",
            "minProperties": 1,
            "patternProperties": {
                "^([a-z]-?)+[a-z]+$": {
                    "additionalProperties": false,
                    "minProperties": 1,
                    "properties": {
                        "filters": {
                            "items": {
                                "minProperties": 1,
                                "patternProperties": {
                                    "^.+$": {
                                        "additionalProperties": false,
                                        "properties": {
                                            "optional": {
                                                "type": "boolean"
                                            }
                                        },
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            },
                            "minItems": 1,
                            "type": "array"
                        },
                        "rules": {
                            "items": {
                                "anyOf": [
                                    {
                                        "$ref": "#/definitions/Rule"
                                    },
                                    {
                                        "$ref": "#/definitions/ContentRule"
                                    }
                                ]
                            },
                            "minItems": 1,
                            "type": "array"
                        },
                        "summary": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "rules"
                    ],
                    "type": "object"
                }
            },
            "propertyNames": {
                "maxLength": 128
            },
            "type": "object"
        }
    },
    "required": [
        "account-id",
        "name",
        "views",
        "body"
    ],
    "type": "object"
}

Manage account’s confdb-schema assertions.¶

Introduced in version 16

GET /api/v2/confdb-schemas/(?P<name>[\\w-]+)¶

POST /api/v2/confdb-schemas/(?P<name>[\\w-]+)¶

Manage account’s confdb-schema assertions.

Usage¶

As mentioned in the introduction, this endpoint can be exercised using the surl command as follows:

surl -s production -e your-email@example.com -X GET https://dashboard.snapcraft.io/api/v2/confdb-schemas

where your-email@example.com has to be an existing account.

GET /api/v2/confdb-schemas[/<name>]¶

reqheader Authorization:: macaroon authorization header for a registered user
status 200:: success
status 400:: error
status 401:: authentication required

GET requests to

/api/v2/confdb-schemas and
/api/v2/confdb-schemas/<name>,

return a list of headers for confdb-schema assertions registered by the requesting user, that match requested criteria.

By default, a GET request to /api/v2/confdb-schemas returns headers for all confdb-schemas owned by the requesting account, each at their latest revision. The same applies to /api/v2/confdb-schemas/<name>, except that the result will contain headers for one specific assertion.

GET Examples¶

Empty response: no confdb-schema assertions found.

Request:

GET /api/v2/confdb-schemas HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...

Response:

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

{
    "assertions": []
}

Fetch all (2 in this example) confdb-schema assertions owned by the requesting account.

Request:

GET /api/v2/confdb-schemas HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...

Response:

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

{
    "assertions": [
        {
            "headers": {
                "account-id": "AccountIDXXXOfTheRequestingUserX",
                "views": {
                    "wifi-setup": {
                        "rules": [
                            {
                                "request": "ssids",
                                "storage": "wifi.ssids"
                            },
                            {
                                "access": "read-write",
                                "request": "ssid",
                                "storage": "wifi.ssid"
                            },
                            {
                                "access": "write",
                                "request": "password",
                                "storage": "wifi.psk"
                            },
                            {
                                "access": "read",
                                "request": "status",
                                "storage": "wifi.status"
                            },
                            {
                                "request": "private.{placeholder}",
                                "storage": "wifi.{placeholder}"
                            }
                        ]
                    }
                },
                "authority-id": "AccountIDXXXOfTheRequestingUserX",
                "body-length": "92",
                "name": "network",
                "sign-key-sha3-384": "XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "timestamp": "2024-03-06T09:00:00Z",
                "type": "confdb-schema"
            },
            "body": "{\n  \"storage\": {\n    \"schema\": {\n      \"wifi\": {\n        \"values\": \"any\"\n      }\n    }\n  }\n}"
        },
        {
            "headers": {
                "account-id": "AccountIDXXXOfTheRequestingUserX",
                "views": {
                    "acme-views": {
                        "rules": [
                            {
                                "request": "acme-headers",
                                "storage": "acme.headers"
                            },
                        ]
                    }
                },
                "authority-id": "AccountIDXXXOfTheRequestingUserX",
                "body-length": "0",
                "name": "network",
                "sign-key-sha3-384": "XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "timestamp": "2024-03-06T09:00:00Z",
                "type": "confdb-schema"
            },
            "body": ""
        }
    ]
}

Fetch the confdb-schema assertion named ‘wifi-setup’ owned by the requesting account.

Request:

GET /api/v2/confdb-schemas/wifi-setup HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...

Response:

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

{
    "assertions": [
        {
            "headers": {
                "account-id": "AccountIDXXXOfTheRequestingUserX",
                "views": {
                    "wifi-setup": {
                        "rules": [
                            {
                                "request": "ssids",
                                "storage": "wifi.ssids"
                            },
                            {
                                "access": "read-write",
                                "request": "ssid",
                                "storage": "wifi.ssid"
                            },
                            {
                                "access": "write",
                                "request": "password",
                                "storage": "wifi.psk"
                            },
                            {
                                "access": "read",
                                "request": "status",
                                "storage": "wifi.status"
                            },
                            {
                                "request": "private.{placeholder}",
                                "storage": "wifi.{placeholder}"
                            }
                        ]
                    }
                },
                "authority-id": "AccountIDXXXOfTheRequestingUserX",
                "body-length": "92",
                "name": "network",
                "sign-key-sha3-384": "XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "timestamp": "2024-03-06T09:00:00Z",
                "type": "confdb-schema"
            },
            "body": "{\n  \"storage\": {\n    \"schema\": {\n      \"wifi\": {\n        \"values\": \"any\"\n      }\n    }\n  }\n}"
        }
    ]
}

POST /api/v2/confdb-schemas¶

reqheader Authorization:: macaroon authorization header for a registered user
status 201:: success
status 400:: error
status 409:: conflict
status 401:: authentication required

POST requests to /api/v2/confdb-schemas are used to register new confdb-schema assertions with the store.

The endpoint expects a valid confdb-schema type assertion, signed with a signing key registered with the store. The endpoint expects an x.ubuntu.assertion content-type request.

/api/v2/confdb-schemas/build-assertion endpoint can be used to obtain confdb-schema assertion headers as JSON, to be used as an input to snap sign, which will sign the assertion and output it in the x.ubuntu.assertion format, ready for sending to /api/v2/confdb-schemas in a POST request.

POST Examples¶

Request:

POST /api/v2/confdb-schemas HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/x.ubuntu.assertion

type: confdb-schema
authority-id: AccountIDXXXOfTheRequestingUserX
account-id: AccountIDXXXOfTheRequestingUserX
name: network
views:
wifi-setup:
    rules:
    -
        request: ssids
        storage: wifi.ssids
    -
        access: read-write
        request: ssid
        storage: wifi.ssid
    -
        access: write
        request: password
        storage: wifi.psk
    -
        access: read
        request: status
        storage: wifi.status
    -
        request: private.{placeholder}
        storage: wifi.{placeholder}
timestamp: 2024-03-06T09:00:00Z
body-length: 92
sign-key-sha3-384: XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
    "storage": {
        "schema": {
            "wifi": {
                "values": "any"
            }
        }
    }
}

<the-key>

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "assertions": [
        {
            "headers": {
                "account-id": "AccountIDXXXOfTheRequestingUserX",
                "views": {
                    "wifi-setup": {
                        "rules": [
                            {
                                "request": "ssids",
                                "storage": "wifi.ssids"
                            },
                            {
                                "access": "read-write",
                                "request": "ssid",
                                "storage": "wifi.ssid"
                            },
                            {
                                "access": "write",
                                "request": "password",
                                "storage": "wifi.psk"
                            },
                            {
                                "access": "read",
                                "request": "status",
                                "storage": "wifi.status"
                            },
                            {
                                "request": "private.{placeholder}",
                                "storage": "wifi.{placeholder}"
                            }
                        ]
                    }
                },
                "authority-id": "AccountIDXXXOfTheRequestingUserX",
                "body-length": "92",
                "name": "network",
                "sign-key-sha3-384": "XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "timestamp": "2024-03-06T09:00:00Z",
                "type": "confdb-schema"
            },
            "body": "{\n  \"storage\": {\n    \"schema\": {\n      \"wifi\": {\n        \"values\": \"any\"\n      }\n    }\n  }\n}"
        }
    ]
}

POST Errors¶

Assertion’s “account-id” header does not match its “authority-id” header.

Request:

POST /api/v2/validation-sets HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/x.ubuntu.assertion

type: confdb-schema
authority-id: AccountIDXXXOfTheRequestingUserX
account-id: AccountIDXYZOfDifferentUserXYZXY
name: network
views:
    wifi-setup:
        rules:
        -
            request: ssids
            storage: wifi.ssids
        -
            access: read-write
            request: ssid
            storage: wifi.ssid
        -
            access: write
            request: password
            storage: wifi.psk
        -
            access: read
            request: status
            storage: wifi.status
        -
            request: private.{placeholder}
            storage: wifi.{placeholder}
timestamp: 2024-03-06T09:00:00Z
body-length: 92
sign-key-sha3-384: XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
    "storage": {
        "schema": {
            "wifi": {
                "values": "any"
            }
        }
    }
}

<the-key>

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error-list": [
        {
            "code": "invalid-request",
            "message": "account-id and authority-id must match the requesting user."
        }
    ]
}

Assertion’s signing key is not registered with the store.

Request:

POST /api/v2/validation-sets HTTP/1.1
Host: dashboard.snapcraft.io
Authorization: Macaroon root=..., discharge=...
Content-Type: application/x.ubuntu.assertion

type: confdb-schema
authority-id: AccountIDXXXOfTheRequestingUserX
account-id: AccountIDXXXOfTheRequestingUserX
name: network
views:
    wifi-setup:
        rules:
        -
            request: ssids
            storage: wifi.ssids
        -
            access: read-write
            request: ssid
            storage: wifi.ssid
        -
            access: write
            request: password
            storage: wifi.psk
        -
            access: read
            request: status
            storage: wifi.status
        -
            request: private.{placeholder}
            storage: wifi.{placeholder}
timestamp: 2024-03-06T09:00:00Z
body-length: 92
sign-key-sha3-384: XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
    "storage": {
        "schema": {
            "wifi": {
                "values": "any"
            }
        }
    }
}

<the-key>

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error-list": [
        {
            "code": "invalid-request",
            "message": "Assertion request not valid: \"could not validate assertion (no matching public key \"XSignXKeyXHashXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" for signature by \"AccountIDXXXOfTheRequestingUserX\")\"."
        }
    ]
}

Response JSON Schema¶

{
    "additionalProperties": false,
    "properties": {
        "assertions": {
            "description": "List of confdb-schema assertions",
            "items": {
                "additionalProperties": false,
                "properties": {
                    "headers": {
                        "additionalProperties": false,
                        "description": "Assertion headers",
                        "properties": {
                            "account-id": {
                                "description": "The \"account-id\" assertion header",
                                "type": "string"
                            },
                            "authority-id": {
                                "description": "The \"authority-id\" assertion header",
                                "type": "string"
                            },
                            "name": {
                                "description": "The \"name\" assertion header",
                                "type": "string"
                            },
                            "sign-key-sha3-384": {
                                "description": "Signing key ID",
                                "type": "string"
                            },
                            "summary": {
                                "type": "string"
                            },
                            "timestamp": {
                                "description": "The \"timestamp\" assertion header",
                                "type": "string"
                            },
                            "type": {
                                "const": "confdb-schema",
                                "description": "The \"type\" assertion header",
                                "type": "string"
                            },
                            "views": {
                                "additionalProperties": false,
                                "description": "Views in a confdb-schema assertion",
                                "minProperties": 1,
                                "patternProperties": {
                                    "^([a-z]-?)+[a-z]+$": {
                                        "additionalProperties": false,
                                        "minProperties": 1,
                                        "properties": {
                                            "filters": {
                                                "items": {
                                                    "minProperties": 1,
                                                    "patternProperties": {
                                                        "^.+$": {
                                                            "additionalProperties": false,
                                                            "properties": {
                                                                "optional": {
                                                                    "type": "boolean"
                                                                }
                                                            },
                                                            "type": "object"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "minItems": 1,
                                                "type": "array"
                                            },
                                            "rules": {
                                                "items": {
                                                    "anyOf": [
                                                        {
                                                            "$ref": "#/definitions/Rule"
                                                        },
                                                        {
                                                            "$ref": "#/definitions/ContentRule"
                                                        }
                                                    ]
                                                },
                                                "minItems": 1,
                                                "type": "array"
                                            },
                                            "summary": {
                                                "type": "string"
                                            }
                                        },
                                        "required": [
                                            "rules"
                                        ],
                                        "type": "object"
                                    }
                                },
                                "propertyNames": {
                                    "maxLength": 128
                                },
                                "type": "object"
                            }
                        },
                        "required": [
                            "type",
                            "authority-id",
                            "series",
                            "account-id",
                            "name",
                            "sequence",
                            "snaps",
                            "sign-key-sha3-384",
                            "timestamp"
                        ],
                        "type": "object"
                    }
                },
                "required": [
                    "headers"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "assertions"
    ],
    "type": "object"
}