.. _confdb-schemas:
========================
Confdb Schemas
========================
Introduction
------------
The *Confdb Schemas API* enables confdb-schema assertions management.
All endpoints require a macaroon authenticated request with no special
permissions.
See :ref:`macaroon-api` 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.
.. _JSON: http://www.json.org
.. _api-confdb-schemas-build-assertion:
Prepare confdb-schema assertion headers ready for signing.
-------------------------------------------------------------------
*Introduced in version 16*
.. http: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
_______
.. include:: ../../examples/requests/confdb_schemas_build_assertion
Errors
______
.. include:: ../../examples/requests/confdb_schemas_build_assertion_errors
Request JSON Schema
___________________
.. code-block:: json
{
"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"
}
.. _api-confdb-schemas:
Manage account's confdb-schema assertions.
-------------------------------------------------------------------
*Introduced in version 16*
.. http:GET:: /api/v2/confdb-schemas/(?P<name>[\\w-]+)
.. http: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.
.. http: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
____________
.. include:: ../../examples/requests/confdb_schemas_get
.. http: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
_____________
.. include:: ../../examples/requests/confdb_schemas_post
POST Errors
___________
.. include:: ../../examples/requests/confdb_schemas_post_errors
Response JSON Schema
____________________
.. code-block:: json
{
"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"
}