Revision as of 05:20, 5 June 2012

Glance v2 api links

Rationale

The jsonschema draft document specifies link description objects as part of a schema document. A link description object defines a format for inferring link relations from the attributes of a document that is an instance of such a schema. Instead of following this format, the present glance v2 api follows the openstack compute api example of embedding link description objects directly in non-schema documents. This blueprint proposes changing version two of the glance api to adopt the jsonschema canonical approach.

Schemas and Examples

The following schemas are missing the property description attributes. Many of these exist in the current code but some will need to be added.

Images Schema

GET /images/schema
{
  "name": "images",
  "properties": {
    "images": {
      "type": "array",
      "items": {
        <COPY IMAGE SCHEMA FROM BELOW>
      }
    },
    "first": {"type": "string"},
    "prev": {"type": "string"},
    "next": {"type": "string"},
    "last": {"type": "string"},
    "schema": {"type": "string"}
  },
  "links": [
    {
      "rel": "first",
      "href": "{first}"
    },
    {
      "rel": "prev",
      "href": "{prev}"
    },
    {
      "rel": "next",
      "href": "{next}"
    },
    {
      "rel": "last",
      "href": "{last}"
    },
    {
      "rel": "describedby",
      "href": "{schema}"
    }
  ]
}

Images Response Example

GET /images?marker=20&limit=10
{
  "images": [
    ...
  ],
  "first": "?limit=10",
  "prev": "?marker=10&limit=10",
  "next": "?marker=30&limit=10",
  "last": "?limit=10&sort_dir=desc",
  "schema": "/images/schema"
}

Image Schema

GET /schemas/image

{
  "name": "image",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 36
    },
    "name": {
      "type": "string",
      "maxLength": 255
    },
    "visibility": {
      "type": "string",
      "enum": ["public", "private"]
    },
    "self": {"type": "string"},
    "file": {"type": "string"},
    "schema": {"type": "string"},
    "access": {"type": "string"},
    <MAYBE ADDITIONAL PROPERTIES - DEPLOYER DETERMINED>
  },
  "additionalProperties": {"type": "string"} <OR FALSE>
  "links": [
    {
      "rel": "describedby",
      "href": "{schema}"
    },
    {
      "rel": "self",
      "href": "{self}"
    },
    {
      "rel": "enclosure",
      "href": "{file}"
    },
    {
      "rel": "related",
      "href": "{access}"
    }
  ]
}

Image Response Example

GET /images/abcd

{
  "id": "abcd",
  "name": "Ubuntu 12.04",
  "visibility": "public",
  "self": "/images/abcd",
  "file": "/images/abcd/file",
  "access": "/images/abcd/access",
  "schema": "/schemas/image",
  <other properties outside of the scope of this proposal>
}

What is to be done about tags? Original spec has them in links, but that would cause a naming conflict and it seems a bit unnecessary if the tags are in-line anyway.

Image Access Records Schema

GET /schemas/access_records
{
  "name": "access_records",
  "properties": {
    "access_records": {
      "type": "array",
      "items": {
        <COPY IMAGE ACCESS RECORD SCHEMA FROM BELOW>
      }
    },
    "first": {"type": "string"},
    "prev": {"type": "string"},
    "next": {"type": "string"},
    "last": {"type": "string"},
    "schema": {"type": "string"}
  },
  "links": [
    {
      "rel": "first",
      "href": "{first}"
    },
    {
      "rel": "prev",
      "href": "{prev}"
    },
    {
      "rel": "next",
      "href": "{next}"
    },
    {
      "rel": "last",
      "href": "{last}"
    },
    {
      "rel": "describedby",
      "href": "{schema}"
    }
  ]
}

Image Access Records Response Example

Image Access Record Schema

GET /schemas/access_record
{
  "name": "access_record",
  "properties": {
    "tenant_id": {
      "type": "string"
    },
    "can_share": {
      "type": "boolean",
      "default": False
    },
    "schema": {
      "type": "string"
    },
    "self": {
      "type": "string"
    },
    "image": {
      "type": "string"
    }
  },
  "additionalProperties": False,
  "links": [
    {
      "rel": "describedby",
      "href": "{schema}"
    },
    {
      "rel": "self",
      "href": "{self}"
    },
    {
      "rel": "up",
      "href": "{image}"
    }
  ]
}

Image Access Record Response Example

Image Tags Schema

Image Tags Response Example