HTTP Link Descriptions
draft-wilde-link-desc-01

Abstract

Interactions with many resources on the Web are driven by links, and these links often define certain expectations about the interactions (such as HTTP methods being allowed, media types being accepted in the request, or URI templates being supported). While these expectations are essential to define the possible interactions, it may be useful to further narrow them down by providing link descriptions, which can help clients to gain more runtime knowledge about the resource they are about to interact with. This memo defines Link Descriptions, a model and associated media type that can be used to describe links by supporting descriptive markup for representing interaction information with links. Link Descriptions can be used by media types (by inclusion or by reference) that seek to make Link Descriptions runtime-capable, without having to create their own representation for them.

Note to Readers

Please discuss this draft on the apps-discuss mailing list.

Online access to all versions and files is available on github.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on August 16, 2014.

Copyright Notice

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Web Links
• 1.2. URI Templates
• 2. Terminology
• 3. Description Concepts
• 3.1. Link Hints
• 3.2. Describing Variables
• 4. Link Descriptions
• 4.1. General Concepts
• 4.2. Link Description Structure
• 4.3. Variable Description Structure
• 5. Examples
• 5.1. Editable Entry
• 5.2. Pageable Collection
• 6. IANA Considerations
• 6.1. Media Type
• 6.2. Link Relation
• 7. Implementation Status
• 8. Security Considerations
• 9. Open Issues
• 10. Change Log
• 10.1. From -00 to -01
• 10.2. Prior to -00
• 11. References
• 11.1. Normative References
• 11.2. Informative References
• Appendix A. Acknowledgements
• Appendix B. Link Description Schema
• Appendix C. XSLT for Generating Link Description HTML
• Author's Address

1. Introduction

Interactions with resources found on the Web often are driven by following links (targeted at URIs [RFC3986]), which can be either fixed links (described in Section 1.1), or can be templated links (using URI Templates [RFC6570]) containing variables (described in Section 1.2). In both cases, the context of the link in most cases provides information that can be essential or helpful when it comes to following a link, which means interacting with the link target: For fixed links, the context may provide (in most cases implicitly, through the use of typed links) allowed interaction methods (such as HTTP verbs) or expectations around the expected media type(s) in requests; for templated links, the context additionally may provide information about how to instantiate the variables provided in the URI Template. This memo defines a schema and a media type that can be used to (partially) represent this information, so that it becomes possible to represent a change in interaction affordances at runtime.

Possible use cases for both scenarios (fixed and templated links) are as follows:

• Fixed Links: AtomPub [RFC5023] defines an "edit" link relation, that informs clients that such a link can be followed to read, update, or delete a resource. This means that a client encountering such a link would conclude that it can try to read, update, or delete the target resource. However, if the resource is not deletable, then an "edit" link could be annotated to indicate that the linked resource cannot be deleted. A client could ignore the annotation and still attempt to delete the resource, but the request would be likely to fail (unless the state of the resource changed in the meantime). This kind of information can be useful for UIs, where it can be used to drive usability features such as disabling certain UI elements.
• Templated Links: URI Templates [RFC6570] define a framework for how to represent and instantiate (with concrete variable assignments) templated URIs, but they don't describe how variables themselves are described, or can be constrained. If a collection resource for example supports paged access to the set of collection members, then it might be useful for a client to know the number of available pages. With this additional knowledge, it is possible to build applications and UIs that specifically take this knowledge into account to drive further interactions with the resource. For a paged collection, it may be a UI that provides direct links to all available pages (if that number is reasonably small). Again, if the collection changes in size between the link being generated, and the link interaction taking place, the information in the link description has become outdated. But this just means that either a client may request a page that doesn't exist anymore, or will not expect a page to exist that now exists. Both of these conditions can be handled well at the time when the client starts interacting with the linked resource.

As described in both cases, it is possible for the link description to become outdated, leading to cases where the assumptions made by the client (based on the link description) and the link target itself do not match anymore. For this reason, ideally a resource should provide a link description for itself, allowing a client to update its expectations. However, since the service generating the link and the service providing the link target often are loosely coupled, link descriptions can be used in links, in descriptions where services expose more runtime information about resources by providing link descriptions for themselves, or in both places.

The following example shows hows both of these mechanisms can be used in one representation, which is based on Atom [RFC4287] and AtomPub [RFC5023]. It also shows the two cases just described, with the first link description being one to "self", while the second link description is describing a different resource.

The link to the feed itself is augmented with a URI Template described in Section 1.2, which allows a client to understand that individual feed pages can be requested (assuming the consumer understands the "concept" identifiers for the described variables). The link to the entry is an augmented typed Web Link described in Section 1.1, which allows a consumer to understand that even though "edit" links typically can be followed via GET, PUT, and DELETE, this particular link should only be followed using a PUT request.

It is worth noting that link descriptions of course can become outdated between the time such a link description has been received by a client, and the time a client actually sends a request when following such a link (this is the case both for "self" links and links to other resources). This means that clients should never depend on a link description being correct, because for example the "edit" link description shown above might start allowing DELETE requests again at any point in time.

1.1. Web Links

One of the defining principles of many services provided on the Web is that they expose linked resources, so that clients can follow the links in order to accomplish application goals. "Web Linking" [RFC5988] establishes a framework of typed links, allowing resources to expose typed links, which then can be followed by clients. While this framework allows clients to select links based on their "types", it does not provide any support for additional runtime information about possible interactions with such a link. As outlined in the AtomPub example above, a link typed as "edit" (as defined and registered by AtomPub) can be followed by using HTTP GET, PUT, or DELETE, and the typed link by itself cannot provide the additional information that some resource may allow updates, but disallows deletion.

"Link Hints" [I-D.nottingham-link-hint] (a draft currently under development) provide a framework for runtime hints that can be used to indicate information that might be made available by the link target resource itself, but ahead of time. For example, a link hint would be able to indicate on an "edit" link that the resource only allows PUT requests, which is something that could also be discovered by sending an HTTP request and getting an HTTP Allow header in the response. However, link hints can save overhead by avoiding round trips, and they also allow to minimize the chances of sending requests that will not succeed.

While link hints can help to avoid overhead and drive client behavior, they are strictly optional. There should be no functional difference of what a client can achieve by using or ignoring link hints; they simply expose information that otherwise would be more costly to acquire.

Since it is potentially expensive to provide link hints in representations (because they may involve interpreting access control data), it is perfectly possible that services provide link hints only on some requests. For example, it would be possible for a service to serve http://example.com/collection as a collection of items with embedded "edit" links, whereas http://example.com/collection?hints=true would result in a representation that would contain additional link hints for each individual "edit" link. This kind of design is outside of the scope of this memo, but it is helpful to illustrate the fact that link hints are nothing but optimizations.

Currently, there is an overlap in what "Link Hints" [I-D.nottingham-link-hint] define, and what is proposed in this memo. While both drafts propose a way how to represent link hints/descriptions, the "Link Hints" draft does not address URI Templates. Removing this overlap is captured in the "Open Issues" Section 9 and should be addressed during the further development and/or alignment of both drafts.

1.2. URI Templates

Following links is the basic principle of interacting with resources on the web, but in many cases, interactions with resources require clients to provide information in addition to just using a fixed URI in a request. In these cases, information can be provided in any way supported by the interaction protocol, and in case of HTTP, this often means that information is either embedded in the URI, in HTTP headers, and/or in the body of the request. For the first case, "URI Template" [RFC6570] provides a standard that allows servers and clients to exchange information about the URIs that a service accepts. The standard specifies "a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion." It allows servers to publish their expectation how a URI should be created by substituting variables with values. Consider the following URI Template:

http://www.example.com/collection{?pagesize,page}

This URI Template allows clients to expand it with two variables assignments, to end up with a concrete URI such as the following:

http://www.example.com/collection?pagesize=10&page=42

URI Templates cover the aspect of starting with a template with variables in it, assigning values to these variables, and then expanding the template into a URI that can be used for sending a request. URI Templates make no assumptions or statements about the meaning or value range of the variables, except for those aspects which are required to cover the process of expanding the template. In particular, for the example given above, there is no indication that the values are supposed to be positive integers (the data type), nor is there any indication that the service may apply certain limits such as a maximum page size (which may change depending on which paged resource is being accessed). As a side note, even if this basic type information was known, URI template expansion could still result in URIs that would not yield successful requests, such as when asking for a page that is beyond the number of pages that a collection has (in a given page size).

The goal of Link Descriptions as defined in this memo is to allow servers to expose a description that provides support both at development time (when a developer uses a media type that uses URI Templates) and at runtime (when a client wants to use a URI template as part of its application flow). Link Descriptions are intended to provide additional information that is not communicated by publishing URI Templates alone. The additional information is both targeted at machines, and at humans. On the human-oriented Web, a Template Description can be seen as the equivalent of a help or documentation page that is linked to from a form, where users can learn more about the values they are supposed to submit within the form.

As a concrete example, a link to a collection like the one above may be exposed in a link description as follows:

<link rel="items" href="http://www.example.com/collection" hreft="http://www.example.com/collection{?pagesize,page}">
  <var name="pagesize" concept="http://example.com/feedpaging/pagesize"/>
  <var name="page" concept="http://example.com/feedpaging/page"/>
</link>

This link description allows a URI Template's variables to be described in terms of URI-identified concepts. By using such a model, it is possible to use global names for URI Template parameters, and bind them to URI Template variable names. The template and the variables int the example above are not specific for any HTTP method, i.e. this link description does not define any constraints in terms of how to use URI Templates differently for different HTTP methods. But this is possible, and is covered in the detailed description below.

The concept URIs are pure identifiers for the purpose of link descriptions; i.e. they should not be considered dereferenceable, and the assumption is that consumers of link descriptions will only use them to match discovered concepts against known concepts. This design does not prohibit to make concept URIs dereferenceable, but this is outside of the scope of link descriptions.

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

3. Description Concepts

The general idea of link descriptions is that they allow to annotate links (URIs or URI Templates) with context that clients can use when they choose to follow those links. In the XML syntax, descriptions are deliberately designed to follow the design of Atom's popular <link> element, which serves as a blueprint for links in many media types. The main idea of link descriptions is to provide a framework which provides services that want to serve this kind of description with a starting point. If these services want, they can reuse the representations for this framework, in whole or in part.

3.1. Link Hints

As mentioned already, "Link Hints" [I-D.nottingham-link-hint] as currently defined overlap with the concepts proposed in this memo. However, this memo goes further than link hints by not just providing hints for URIs, but for URI Templates as well. Based on the current link hint model defined in that draft, a link hint is a name/value pair, where the name is either a registered link hint, or a URI. The allowed value space depends on the link hint, and in the current model, structured values must be encoded in JSON. A link may have any number of link hints, but only one link hint with a given name.

3.2. Describing Variables

When a link description uses a URI Template, then this template will very likely contain variables. Variables can be described when using Link Descriptions. For each variable contained in the URI Template, it is possible to use the following description methods:

• Concept: It is possible to associate a variable with a concept, so that media types and applications can make an association between the concepts they are defining/exposing, and how they are exposed in URI Templates. Concepts can be identified by using a URI as an identifier. This specification defines no interactions with this URI identifier and makes no assumption about possible representations, should this URI be dereferenceable and yield some representation.
• Documentation: Documentation constructs can be associated with variables, which allows Link Descriptions to attach human-readable information to individual variables. The documentation model has the ability to support multi-lingual human-oriented documentation.

For the purpose of this specification, the term "description" should be interpreted loosely. Description aspects such as concepts and documentation do not prescribe a description framework; they simply provides a structure how to deliver these descriptions, so that clients can use them when making decisions about which links to follow, and how to follow them.

4. Link Descriptions

Link Descriptions are based on a URI Template, and add descriptive elements that allow publishers of URI Templates to describe the URI Template as a whole, and to add individual descriptions of all variables in the template. The idea of Link Descriptions is that they are made available at design time and/or at runtime, so that clients encountering URI Templates as part of HTTP services can find more information about the template itself.

Ideally, every URI template exposed in an HTTP service should be accompanied by a link to a Link Description. In those XML-based HTTP services where URI Templates are exposed in XML attributes named "hreft", the suggestion is to add a link to the corresponding Link Description in an "hrefd" XML attribute.

4.1. General Concepts

As mentioned in Section 1.2, most of the descriptions in this spec do not prescribe a specific description framework. While variables (Section 4.3) can be described with a built-in vocabulary of datatypes, most other descriptions are either for human consumption, or do rely on some external description framework. To attach these descriptions to both the template as a whole, and individual variables, this specification reuses the "appinfo" and "documentation" elements from XML Schema Part 1. These elements carry a "source" attribute, which is used "to supplement the local information." For example, when a description of a variable is done formally using a specific description framework, this would best translate to use appinfo elements, and to add an identifier to them which would identify the description framework in question. As a result, any client knowing this particular description framework would be able to interpret the variable description in the Link Description.

4.2. Link Description Structure

An interaction is described by including the URI Template itself, and optionally adding documentation and/or appinfo elements to add human- or machine-readable descriptions.

4.3. Variable Description Structure

A variable is described by specifying the variable name. Variables can refer to a "concept" associated with a variable, which can by identified by URI. This specification makes no provision how such a concept is defined and/or described/documented, but it allows consumers of a Link Description to match their understanding of certain concepts to those identifiers, which then establishes a binding between the concept, and the variable it has been bound to.

A variable can have a default value, in which case the assumption is that excluding this variable from a request has the same effect as including it with the default value. Since Link Descriptions are runtime concepts, however, there is no guarantee that a service might not use a different value between the time when the Link Description was retrieved, and the time when a request based on it is being sent.

Variable descriptions can optionally add documentation and/or appinfo elements to add human- or machine-readable descriptions.

5. Examples

...

5.1. Editable Entry

...

All the example use "documentation" elements which are entirely optional, but can help to improve the usefulness of link descriptions for developers.

5.2. Pageable Collection

...

6. IANA Considerations

6.1. Media Type

The Internet media type [RFC6838] for a Link Description document is application/ldesc+xml (using the "+xml" suffix as defined and registered by RFC 6839 [RFC6839]).

Type name:

application

Subtype name:

ldesc+xml

Required parameters:

none

Optional parameters:

profile

• The "profile" link relation [RFC6906] allows "resource representations to indicate that they are following one or more profiles. A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms." If the application/ldesc+xml media type is use with a profile parameter, this refers to a profile as defined by [RFC6906], making it easier for extensions of the link description media type to identify themselves.

Encoding considerations:

Same as encoding considerations of application/xml as specified in [RFC3023].

Security considerations:

This media type has all of the security considerations described in [RFC3023], plus those listed in Section 8.

Interoperability considerations:

N/A

Published specification:

RFC XXXX

Applications that use this media type:

Applications that publish descriptions of URI Interactions.

Additional information:

Magic number(s):

none

File extension(s):

No specific file extension proposed, but as a general rule, XML data often uses ".xml" as the file extension.

Macintosh file type code(s):

TEXT

Person & email address to contact for further information:

Erik Wilde <dret@berkeley.edu>

Intended usage:

COMMON

Restrictions on usage:

none

Author:

Erik Wilde <dret@berkeley.edu>

Change controller:

IESG

6.2. Link Relation

The link relation type below will be registered by IANA per Section 6.2.1 of RFC 5988 [RFC5988]:

• Relation Name: ldesc
• Description: Linking to a resource that can be used as a link description for requesting runtime information about a particular context's interaction affordances.
• Reference: RFC XXXX
• Notes: Link Descriptions can be used in all scenarios where clients want to create requests that represent a query into the context resource. The media type of the context resource and the media type of the link description resource are not constrained by this specification.

7. Implementation Status

Note to RFC Editor: Please remove this section before publication.

This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in RFC 6982 [RFC6982]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.

According to RFC 6982, "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".

8. Security Considerations

...

9. Open Issues

• If and how to use profiles (example in Section 5); if profile use is recommended, define a suggested profile URI for other specs to use?
• How to handle variables in Level 4 templates that are supposed to have composite values?
• If a template is refined in an incremental process (such as for example faceted search services), does it make sense to be able to add a "back" link and/or "home" link, so that clients can find the "most general" version easily?
• How does this interact with "faceted search" scenarios? Does incremental refinement of URI Template Descriptions somehow nicely and naturally map into faceted search scenarios?
• Is there a concept of how Template Descriptions (and thus URI Templates) can be reused? Should there be an inclusion facility or something along those lines? If so, what's the model for that? Initial thoughts on possibilities can be found on this page
• Should there be some recommended link relation to use when linking to a Template Description from within the context of a URI Template?
• While currently everything is defined in XML, providing alternative serializations (JSON and RDF) might be an interesting thing to consider.
• Should there be a "Template" HTTP header field, listing a resource's URI Template and, optionally, containing a link to a description resource for it (basically, a rel="ldesc" link)?
• What about using CURIE for the variable names, thus eliminating the need for separate concept URIs? This would need prefix bindings, which in XML would just up as regular namespace declarations. It might quite be a bit more problematic in non-XML contexts, such as serving a URI Template in an HTTP header.
• Support for "HTTP Prefer" [I-D.snell-http-prefer] might need another link hint, so that clients know which preferences they might use.

10. Change Log

Note to RFC Editor: Please remove this section before publication.

10.1. From -00 to -01

• Adding "Template" HTTP header field as an open issue.
• Adding CURIEs as one possible convention to use for variable names, so that "Concept URIs" are embedded in the template itself, and not external.
• Adding "HTTP Prefer" [I-D.snell-http-prefer] as an open issue.
• Updated author address.

10.2. Prior to -00

An earlier variation of a similar idea was published as "Template Descriptions" [I-D.wilde-template-desc]. However, since this earlier draft was exclusively focusing on interactions with links driven by URI Templates [RFC6570], instead of looking at links in general, it was sufficiently distinct to start a new draft, instead of evolving the existing one.

11. References

11.1. Normative References

11.2. Informative References

Appendix A. Acknowledgements

Thanks for comments and suggestions provided by Dmitry Limonov.

Appendix B. Link Description Schema

Appendix C. XSLT for Generating Link Description HTML

Author's Address