Revision as of 19:10, 30 May 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

Images Schema

GET /images/schema
{
  "name": "images",
  "properties": {
    "images": {
      "type": "array",
      "items": {
        "extends": "http://glance/v2/schemas/image"
      }
    },
    "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.