Loading ...
Sorry, an error occurred while loading the content.

Re: [rest-discuss] Using HTTP Link: headers for web linking non-hypertext

Expand Messages
  • mike amundsen
    FWIW, Link *Headers* make sense to me when the link are metadata about the resource. However, when the links are to be treated as first-class resources
    Message 1 of 42 , Jun 30, 2009
    • 0 Attachment
      FWIW, Link *Headers* make sense to me when the link are metadata about the resource. However, when the links are to be treated as first-class resources themselves, I think Link Headers is not the right choice. For example, I assert that links appearing in the <head /> section of typical HTML documents are metadata. Links that appear in the <body /> section are not.

      I am not privy to the details of your particular use of links, but I get the impression that they are more than metadata. If true, I would consider placing the links either in the body of the resource or, when the resource does not support body links easily (certain binary files, etc.), I would add a single link header (Link: <http://www.example.org/resource123/links>; rel=related) that points to the related resource that holds all the links. One possible advantage of this approach is that the related links are now exposed in a way that easily allows searching and filtering using well-established mechanisms.

      Also, this sentence from your last post caught my eye:
      <snip>
      It's unavoidable (I think) that a case in which you might simply add a foreign key or a bridge table when thinking relationally, you need to do lots of contortions to do RESTfully.
      </snip>

      This is very true. For me, that's an excellent reminder that the relational approach is not the same as a RESTful approach.

      mca
      http://amundsen.com/blog/



      On Tue, Jun 30, 2009 at 21:32, Peter Keane <pkeane@...> wrote:




      On Tue, Jun 30, 2009 at 5:17 PM, Subbu Allamaraju <subbu@...> wrote:
      This looks just right for a one-many link (as in my #1 option -- post to a
      cart "collection" resource) in which the "one" is obvious and easily
      discoverable (like a cart).  But a common case I run into is a one in which
      a resource must be linked to any of a large number of possible related
      resources.  (In my case it is a digital image library, in which we regularly
      need to create links between items, e.g., a link from a photo of an
      architect to an image of a building that she created.).  We have needed to
      devise as general an operation as possible to *relate* two resources.  In
      the case of a cart and a product, it is obvious what the relationship will
      be once it is created.  We have need to create links between resources that
      may have any of a large number of relations (e.g., "created-by").  I wish to
      stay in the realm of Atom (avoiding complexities of RDF).  I am reminded
      somewhat here by the work going on in activities streams....  Anyway, I
      agree with Sam that it is currently an unsolved problem with wide
      applicability.


      So, when you let clients establish links between resources, who controls whether a link is valid or bogus?

      What is the advantage of the client owning this problem?

      Forgetting about HTTP and REST for a bit, would you still take the same approach if you are building this application using a different style? What I am getting at is, is the "link management" problem real, or is it a manifestation of an implementation choice?

      Good questions.  Certainly, it'll be the server that controls what's a valid "linkage", but the range of possibilities might be (nearly) infinite.  And I agree there are few cases in which the problem should be owned by the client. (I can't help but think about all of the sticky issue around RDF here -- by whose authority is a particular assertion made given that the power to make an assertion is "granted" to any "client"?).

      I can decompose the problem such that a UI might be a drag-and-drop, an "add-to-cart" button, etc.  More commonly, in my digital library case, I'll have an embedded search feature where I allow the user to do an open search over the collection and select any found items to be "related" to the current item (and probably provide a pull-down selection of relation types). 

      Just under the hood, though, a link is being created between these two resources.  Since the range of possible links is so huge, I'd find it hard to offer a @rel=buy link as in your example.  I suppose a reasonable extrapolation of that would be to provide a "linker" global resource that would allow me, say, to post form encoded: id_one=123&id_two=224&relation=created-by (?).  OR perhaps each item has it's own <link rel="http://example.org/linker" href="http://example.org/item/linker/123"/> that I could post an id and relationship type to (hmmm -- need to provide a way for client to know the possible relation types -- possibly an atom:link for each relation type that I can POST to?).

      Anyway, it gets unwieldy quickly.  It's unavoidable (I think) that a case in which you might simply add a foreign key or a bridge table when thinking relationally, you need to do lots of contortions to do RESTfully.  When all is said and done, link headers seems reasonably elegant.  I agree with you, though, that it potentially gives the client too much (unconstrained, or at least not constrained in a discoverable way) ownership of the problem.

      --peter





      Subbu




    • Sam Johnston
      ... Ok so here s a separate but similar issue. I ve just released an Internet-Draft
      Message 42 of 42 , Jul 1 4:17 PM
      • 0 Attachment
        On Wed, Jul 1, 2009 at 6:37 PM, Subbu Allamaraju <subbu@...> wrote:
        The key question being debated is whether link management is a client concern or it is a consequence of some protocol operation performed by a client.

        Ok so here's a separate but similar issue. I've just released an Internet-Draft (draft-johnston-http-category-header) which allows web resources to be categorised, following Atom's example. Basically between this and the Link: header you can "unwrap" individual resources which leaves a more performant, intuitive "universal" interface (while still using Atom for collections).

        Again both clients and servers will be wanting to set categories but I would say certainly that this should be done directly via the headers rather than via some "controller" with associated rules.

        Sam

        Internet Engineering Task Force                              S. Johnston
        Internet-Draft Australian Online Solutions
        Intended status: Experimental July 1, 2009
        Expires: January 2, 2010


        Web Categories
        draft-johnston-http-category-header-00

        Status of this Memo

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

        Internet-Drafts are working documents of the Internet Engineering
        Task Force (IETF), its areas, and its working groups. Note that
        other groups may also distribute working documents as Internet-
        Drafts.

        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."

        The list of current Internet-Drafts can be accessed at
        http://www.ietf.org/ietf/1id-abstracts.txt.

        The list of Internet-Draft Shadow Directories can be accessed at
        http://www.ietf.org/shadow.html.

        This Internet-Draft will expire on January 2, 2010.

        Copyright Notice

        Copyright (c) 2009 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 in effect on the date of
        publication of this document (http://trustee.ietf.org/license-info).
        Please review these documents carefully, as they describe your rights
        and restrictions with respect to this document.

        Abstract

        This document specifies the Category header-field for HyperText
        Transfer Protocol (HTTP), which enables the sending of taxonomy
        information in HTTP headers.



        Johnston Expires January 2, 2010 [Page 1]

        Internet-Draft Abbreviated Title July 2009


        Table of Contents

        1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
        1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 3
        2. Categories . . . . . . . . . . . . . . . . . . . . . . . . . . 3
        3. The Category Header Field . . . . . . . . . . . . . . . . . . . 4
        3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 4
        4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
        4.1. Category Header Registration . . . . . . . . . . . . . . . 5
        5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5
        6. Internationalisation Considerations . . . . . . . . . . . . . . 5
        7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
        7.1. Normative References . . . . . . . . . . . . . . . . . . . 6
        7.2. Informative References . . . . . . . . . . . . . . . . . . 6
        Appendix A. Notes on use with HTML . . . . . . . . . . . . . . . . 7
        Appendix B. Notes on use with Atom . . . . . . . . . . . . . . . . 7
        Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . . 8
        Appendix D. Document History . . . . . . . . . . . . . . . . . . . 8
        Appendix E. Outstanding Issues . . . . . . . . . . . . . . . . . . 8
        Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9































        Johnston Expires January 2, 2010 [Page 2]

        Internet-Draft Abbreviated Title July 2009


        1. Introduction

        A means of indicating categories for resources on the web has been
        defined by Atom [RFC4287]. This document defines a framework for
        exposing category information in the same format via HTTP headers.

        The atom:category element conveys information about a category
        associated with an entry or feed. A given atom:feed or atom:entry
        element MAY have zero or more categories which MUST have a "term"
        attribute (a string that identifies the category to which the entry
        or feed belongs) and MAY also have a scheme attribute (an IRI that
        identifies a categorization scheme) and/or a label attribute (a
        human-readable label for display in end-user applications).

        Similarly a web resource may be associated with zero or more
        categories as indicated in the Category header-field(s). These
        categories may be divided into separate vocabularies or "schemes"
        and/or accompanied with human-friendly labels.

        [[ Feedback is welcome on the ietf-http-wg@... mailing list,
        although this is NOT a work item of the HTTPBIS WG. ]]

        1.1. Requirements Language

        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 BCP 14, [RFC2119], as
        scoped to those conformance targets.

        This document uses the Augmented Backus-Naur Form (ABNF) notation of
        [RFC2616], and explicitly includes the following rules from it:
        quoted-string, token. Additionally, the following rules are included
        from [RFC3986]: URI.


        2. Categories

        In this specification, a category is a grouping of resources by
        'term', from a vocabulary ('scheme') identified by an IRI [RFC3987].
        It is comprised of:

        o A "term" which is a string that identifies the category to which
        the resource belongs.

        o A "scheme" which is an IRI that identifies a categorization scheme
        (optional).





        Johnston Expires January 2, 2010 [Page 3]

        Internet-Draft Abbreviated Title July 2009


        o An "label" which is a human-readable label for display in end-user
        applications (optional).

        A category can be viewed as a statement of the form "resource is from
        the {term} category of {scheme}, to be displayed as {label}", for
        example "'Loewchen' is from the 'dog' category of 'animals', to be
        displayed as 'Canine'".


        3. The Category Header Field

        The Category entity-header provides a means for serialising one or
        more categories in HTTP headers. It is semantically equivalent to
        the atom:category element in Atom [RFC4287].

        Category = "Category" ":" #category-value
        category-value = term *( ";" category-param )
        category-param = ( ( "scheme" "=" <"> scheme <"> )
        | ( "label" "=" quoted-string )
        | ( "label*" "=" enc2231-string )
        | ( category-extension ) )
        category-extension = token [ "=" ( token | quoted-string ) ]
        enc2231-string = <extended-value, see [RFC2231], Section 7>
        term = token
        scheme = URI

        Each category-value conveys exactly one category but there may be
        multiple category-values for each header-field and/or multiple
        header-fields per [RFC2616].

        Note that schemes are REQUIRED to be absolute URLs in Category
        headers, and MUST be quoted if they contain a semicolon (";") or
        comma (",") as these characters are used to separate category-params
        and category-values respectively.

        The "label" parameter is used to label the category such that it can
        be used as a human-readable identifier (e.g. a menu entry).
        Alternately, the "label*" parameter MAY be used encode this label in
        a different character set, and/or contain language information as per
        [RFC2231]. When using the enc2231-string syntax, producers MUST NOT
        use a charset value other than 'ISO-8859-1' or 'UTF-8'.

        3.1. Examples

        NOTE: Non-ASCII characters used in prose for examples are encoded
        using the format "Backslash-U with Delimiters", defined in Section
        5.1 of [RFC5137].




        Johnston Expires January 2, 2010 [Page 4]

        Internet-Draft Abbreviated Title July 2009


        For example:
        Category: dog

        indicates that the resource is in the "dog" category.
        Category: dog; label="Canine"; scheme="http://purl.org/net/animals"

        indicates that the resource is in the "dog" category, from the
        "http://purl.org/net/animals" scheme, and should be displayed as
        "Canine".

        The example below shows an instance of the Category header encoding
        multiple categories, and also the use of [RFC2231] encoding to
        represent both non-ASCII characters and language information.
        Category: dog; label="Canine"; scheme="http://purl.org/net/animals",
        lowchen; label*=UTF-8'de'L%c3%b6wchen";
        scheme="http://purl.org/net/animals/dogs"

        Here, the second category has a label encoded in UTF-8, uses the
        German language ("de"), and contains the Unicode code point \u'00F6'
        ("LATIN SMALL LETTER O WITH DIAERESIS").


        4. IANA Considerations

        4.1. Category Header Registration

        This specification adds an entry for "Category" in HTTP to the
        Message Header Registry [RFC3864] referring to this document:
        Header Field Name: Category
        Protocol: http
        Status: standard
        Author/change controller:
        IETF (iesg@...)
        Internet Engineering Task Force
        Specification document(s):
        [ this document ]


        5. Security Considerations

        The content of the Category header-field is not secure, private or
        integrity-guaranteed, and due caution should be exercised when using
        it.


        6. Internationalisation Considerations

        Category header-fields may be localised depending on the Accept-



        Johnston Expires January 2, 2010 [Page 5]

        Internet-Draft Abbreviated Title July 2009


        Language header-field, as defined in section 14.4 of [RFC2616].

        Scheme IRIs in atom:category elements may need to be converted to
        URIs in order to express them in serialisations that do not support
        IRIs, as defined in section 3.1 of [RFC3987]. This includes the
        Category header-field.


        7. References

        7.1. Normative References

        [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
        Requirement Levels", BCP 14, RFC 2119, March 1997.

        [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
        Word Extensions: Character Sets, Languages, and
        Continuations", RFC 2231, November 1997.

        [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
        Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
        Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

        [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
        Procedures for Message Header Fields", BCP 90, RFC 3864,
        September 2004.

        [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
        Resource Identifier (URI): Generic Syntax", STD 66,
        RFC 3986, January 2005.

        [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
        Identifiers (IRIs)", RFC 3987, January 2005.

        [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication
        Format", RFC 4287, December 2005.

        [RFC5137] Klensin, J., "ASCII Escaping of Unicode Characters",
        RFC 5137, February 2008.

        7.2. Informative References

        [OCCI] Open Grid Forum (OGF), Edmonds, A., Metsch, T., Johnston,
        S., and A. Richardson, "Open Cloud Computing Interface
        (OCCI)", <http://purl.org/occi>.

        [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T.
        Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1",



        Johnston Expires January 2, 2010 [Page 6]

        Internet-Draft Abbreviated Title July 2009


        RFC 2068, January 1997.

        [W3C.REC-html401-19991224]
        Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01
        Specification",
        <http://www.w3.org/TR/1999/REC-html401-19991224>.

        [W3C.WD-html5-20090423]
        Hyatt, D. and I. Hickson, "HTML 5", April 2009,
        <http://www.w3.org/TR/2009/WD-html5-20090423>.

        [draft-nottingham-http-link-header]
        Nottingham, M., "Web Linking",
        draft-nottingham-http-link-header-05 (work in progress),
        April 2009.

        [rel-tag-microformat]
        Celik, T., Marks, K., and D. Powazek, "rel="tag"
        Microformat", <http://microformats.org/wiki/rel-tag>.


        Appendix A. Notes on use with HTML

        In the absence of a dedicated category element in HTML 4
        [W3C.REC-html401-19991224] and HTML 5 [W3C.WD-html5-20090423],
        category information (including user supllied folksonomy
        classifications) MAY be exposed using HTML A and/or LINK elements by
        concatenating the scheme and term:
        category-link = scheme term
        scheme = URI
        term = token

        These category-links MAY form a resolveable "tag space" in which case
        they SHOULD use the "tag" relation-type per [rel-tag-microformat].

        Alternatively META elements MAY be used:

        o where the "name" attribute is "keywords" and the "content"
        attribute is a comma-separated list of term(s)

        o where the "http-equiv" attribute is "Category" and the "content"
        attribute is a comma-separated list of category-value(s)


        Appendix B. Notes on use with Atom

        Where the cardinality is known to be one (for example, when
        retrieving an individual resource) it MAY be preferable to render the



        Johnston Expires January 2, 2010 [Page 7]

        Internet-Draft Abbreviated Title July 2009


        resource natively over HTTP without Atom structures. In this case
        the contents of the atom:content element SHOULD be returned as the
        HTTP entity-body and metadata including the type attribute and atom:
        category element(s) via HTTP header-field(s).

        This approach SHOULD NOT be used where the cardinality is guaranteed
        to be one (for example, search results which MAY return one result).


        Appendix C. Acknowledgements

        The author would like to thank Mark Nottingham for his work on Web
        Linking [draft-nottingham-http-link-header] (on which this document
        was based) and to the authors of [RFC2068] for specification of the
        Link: header-field on which this is based.

        The author would like to thank members of the OGF's Open Cloud
        Computing Interface [OCCI] working group for their contributions and
        others who commented upon, encouraged and gave feedback to this
        draft.


        Appendix D. Document History

        [[ to be removed by the RFC editor should document proceed to
        publication as an RFC. ]]

        -00

        * Initial draft based on draft-nottingham-http-link-header-05


        Appendix E. Outstanding Issues

        [[ to be removed by the RFC editor should document proceed to
        publication as an RFC. ]]

        The following issues are oustanding and should be addressed:

        1. Is extensibility of Category headers necessary as is the case for
        Link: headers? If so, what are the use cases?

        2. Is supporting multi-lingual representations of the same
        category(s) necessary? If so, what are the risks of doing so?

        3. Is a mechanism for maintaining Category header-fields required?
        If so, should it use the headers themselves or some other
        mechanism?



        Johnston Expires January 2, 2010 [Page 8]

        Internet-Draft Abbreviated Title July 2009


        4. Does this proposal conflict with others in the same space? If
        so, is it an improvement on what exists?


        Author's Address

        Sam Johnston
        Australian Online Solutions
        GPO Box 296
        Sydney, NSW 2001

        Email: samj@...
        URI: http://samj.net/






































        Johnston Expires January 2, 2010 [Page 9]



      Your message has been successfully submitted and would be delivered to recipients shortly.