Link semantics & HTTP Link Header rendering

Open Issues

• Is a Client allowed to supply Link Headers in a POST to create a Resource with associated Links? If so, is it a SHOULD or a MUST in the spec?
• Is a Client allowed to add new Links to a Resource through a PUT request? If so, OPTIONAL, SHOULD or MUST?
• Comments on the Link Header rendering of Actions ??
• Do we need to handle credentials when linking to external resources, if so how?
• Currently there's nothing to prevent a link from linking to another link
• Links have a unique ID however they inherit from Kind which has no ID - where is the ID defined?

TODO

• DELETE example?

Overview

Create, Read, Update and Delete (CRUD) semantics

Create

A client POST request MUST include the required attributes specified by the core link Category, http://schemas.ogf.org/occi/core#link. An OCCI server MAY enforce additional attributes at creation time if the link has been subtyped using additional categories. An OCCI server SHOULD verify the submitted Link source and target are existing Resources and refuse the request if it would result in a "dangling" link.

Read

An OCCI server response to a client GET request MUST include all categories defining the requested Link's type.

Update

A server MAY refuse a client PUT request from updating certain Link attributes. Specifically the occi.link.source and occi.link.target attributes of http://schemas.ogf.org/occi/core#link MAY be refused if the link has been subtyped for domain-specific purposes.

Delete

An OCCI server MUST NOT delete the associated Resources upon receiving a client DELETE request for a Link.

Link Header rendering

In addition to the Link target, self parameter and optional title the following additional information MAY be included in a Link Header.

• The target type defined by a space separated list of categories in the rel Link Header parameter.
• The Link type defined by a space separated list of categories in the category Link Header Extension parameter.
• A set of associated attributes defined by the categories of the Link type. Each attribute MUST be rendered as a Link Header Extension parameter.

The Link Header rendering thus allow for both in-line and out-band representation of Link attributes. It is up to the server implementation to decide which information to include as long as the above rules are respected. In order to avoid unnecessary traffic it is RECOMMENDED to include at least the target type. When the response BODY is empty or does not include all Link information it is RECOMMENDED the server use the full in-bound Link Header rendering.

Examples

List existing Links

  GET /link HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 01 Sep 2010 08:58:22 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Content-Type: text/uri-list; charset=utf-8
  
  /link/123-123-123
  /link/234-234-234
  /link/345-345-345

Create a new Link

  POST /link/ HTTP/1.0
  Accept: */*
  Category: link; scheme="http://schemas.ogf.org/occi/core#",
      disk_drive; scheme="http://example.com/occi/link#"
  Attribute: occi.link.source="/compute/vm01",
             occi.link.target="/storage/disk03",
	     com.example.drive.interface="ide"
  
  HTTP/1.0 201 CREATED
  Date: Wed, 01 Sep 2010 09:12:50 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Location: http://example.com/link/456-456-456

Read specific Link

  GET /link/456-456-456 HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 01 Sep 2010 09:22:28 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Category: link; scheme="http://schemas.ogf.org/occi/core#",
      disk_drive; scheme="http://example.com/occi/link#"
  Attribute: occi.link.source="/compute/vm01",
             occi.link.target="/storage/disk03",
	     com.example.drive.interface="ide"

Minimal HTTP Link Header rendering

  GET /compute/vm01 HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 01 Sep 2010 09:32:28 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Category: resource; schema="http://schemas.ogf.org/occi/core#",
            compute; scheme="http://schemas.ogf.org/occi/infrastructure#"
  Link: </storage/disk03>;
        self="/link/456-456-456";
        title="Storage Disk 03"
  Attribute: occi.compute.cores="2", occi.compute.memory="2.5", occi.compute.state="inactive", ...

Recommended HTTP Link Header rendering

  GET /compute/vm01 HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 01 Sep 2010 09:32:28 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Category: resource; schema="http://schemas.ogf.org/occi/core#",
            compute; scheme="http://schemas.ogf.org/occi/infrastructure#"
  Link: </storage/disk03>;
        rel="http://schemas.ogf.org/occi/core#resource http://schemas.ogf.org/occi/infrastructure#storage";
        self="/link/456-456-456";
        title="Storage Disk 03"
  Attribute: occi.compute.cores="2", occi.compute.memory="2.5", occi.compute.state="inactive", ...

Full-fledged in-line HTTP Link Header rendering

  GET /compute/vm01 HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 01 Sep 2010 09:32:28 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Category: resource; schema="http://schemas.ogf.org/occi/core#",
            compute; scheme="http://schemas.ogf.org/occi/infrastructure#"
  Link: </storage/disk03>;
        rel="http://schemas.ogf.org/occi/infrastructure#storage http://example.com/occi/resource#storage";
        self="/link/456-456-456";
        title="Storage Disk 03";
        category="http://schemas.ogf.org/occi/core#link http://example.com/occi/link#disk_drive";
        com.example.drive.interface="ide"
  Attribute: occi.compute.cores="2", occi.compute.memory="2.5", occi.compute.state="inactive", ...

Notes

Until the new HTTP Rendering document is finished I thought an example on how to render Actions using the Link header would be useful.

Regarding the updates in Core the above examples are still valid. The updated spec on Category hierarchies will however reduce the number of Categories which MUST be displayed although the above approach of displaying the complete Set of Categories is still valid.

Actions and the Link Header

A reference to an Action supported by a Resource is also rendered using the Link Header. It is very important to realise the distinction between the base type Link and the Link Header. The later is a HTTP Header construct which is used to display a generic link referring to an arbitrary target, i.e. the Link Header is not only for Links. For example the Link Header can be used to refer to documentation or other targets with no relation to the resource types defined by OCCI.

The link rendered in a Link Header does not necessarily correspond to the OCCI Link base type

Let us have a look at the different Link Header parameters and see what they are used for:

• <target> The target IRI of the link rendered in the Link Header.
• title= An arbitrary string.
• rel= The relation type. Describes the resource the Link Header points to.
• self= The link rendered by the Link Header is represented by a REST resource found at the given URL.
• category= The type of the resource referred to by the self= parameter.

Examples

A Compute Resource with an associated Action

  GET /compute/vm02 HTTP/1.0
  Accept: */*

  HTTP/1.0 200 OK
  Date: Wed, 06 Sep 2010 09:32:28 GMT
  Server: occi-server/1.0 (linux) OCCI/1.0
  Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"
  Link: </compute/vm02;action=start>;
        rel="http://schemas.ogf.org/occi/infrastructure/compute/action#start";
        title="Start VM"
  Attribute: occi.compute.cores="1", occi.compute.memory="1.5", occi.compute.state="inactive", ...

Contributors

• Editors: Ralf Nyrén

Attachments:

fat_links.png [Link/fat_links.png]