Obsolete:Glance-api-v2-links

= 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": {  }   },    "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"},  }, "additionalProperties": {"type": "string"}  "links": [ {     "rel": "describedby", "href": "{schema}" },   {      "rel": "self", "href": "{self}" },   {      "rel": "enclosure", "href": "{file}" },   {      "rel": "related", "href": "{access}" } ] }

TODO: Update the above with the schema parameters that have been recently added to glance.schema.API.

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",  }

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": {  }   },    "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 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 Tags Schema
GET /schemas/tags { "name": "tags", "properties": { "tags": { "type": "array", "items": { "type": "string", "maxLength": 255 }   },    "image": { "type": "string" } },  "additionalProperties": False, "links": [ {     "rel": "up", "href": "{image}" } ] }

This approach assumes we will not do pagination for tags.