[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
Internet Draft                                             K. Ota, NTT
<draft-ntt-http-version-00>                          K. Takahashi, NTT
                                               K. Sekiya, NTT Software
Expires May 1997                                     November 06, 1996


        Version management with meta-level links via HTTP/1.1

Status of Memo

     This document is an Internet-Draft.  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.''

     To learn the current status of any Internet-Draft, please check
     the ``1id-abstracts.txt'' listing contained in the Internet-
     Drafts Shadow Directories on ftp.is.co.za (Africa),
     nic.nordu.net (Europe), munnari.oz.au (Pacific Rim),
     ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).

     Distribution of this document is unlimited. Please send comments
     to Kenji Ota, NTT (ota@nttlabs.com), Kenji Takahashi
     (kt@nttlabs.com), or Kazuchika Sekiya (sekiya@ntts.com).

Abstract

        This draft describes version management of the resources with
        some extensions to HTTP/1.1.
        The main point of our approach is to use meta-level links,
        which is not an anchor of HTML format, but an attribute of the
        resource. So, the contents need not to be an HTML format.

1. Introduction

        Conventionally, most resources are linked each other with
        links described in HTML files. This mechanism is not useful in
        version management, because HTML files have to be edited in
        order to manipulate the links between the versions of a
        resource.

         This document describes a mechanism for version management of
        resources, which uses meta-level links. A meta-level link
        relates two resources outside the contents of resources. So,
        the contents need not to be an HTML format.

         This document also describes the classification of the
        PUT method. It is used for the server to distinguish between
        normal resources and versioned resources.

         The locking mechanism is also described. It prevents multiple
        clients from editing the same resource at one time. So, our
        policy of locking is similar to RCS.

2. Meta-level links

        A meta-level link, that is meta-information of resources,
        relates two resources outside the contents of resources.
        It is independent from the contents of resource. So, the
        content of the resource needs not to be HTML format.
        The draft specification of HTTP/1.1[1] specifies "Link:"
        header field in the appendices chapter.

        The LINK and UNLINK methods manipulate the meta-level links. These
        methods are also specified in the appendices chapter of
        HTTP/1.1 specification.

        If the GET or HEAD request sends to the server, the server
        returns the "Link:" header in the response.
        If the PUT request sends to the server with the "Link:"
        header, the server establishes the links between the
        resource specified by Request-URI and resources specified in
        the "Link:" header.

        The meta-level links can be used to manage the versions of the
        resources. The chapter 5 describes details of version
        management using this meta-level links. The meta-level links
        themselves are so generic as to used for other purposes than
        version management. For example, annotations to some web
        contents can be linked by using this.

3. Locking mechanism

        We propose LOCK/UNLOCK method for locking a resource.
        Locking a resource means that the server excludes the other
        requests for update to the same resource, in order to
        make sure that only one user can update a resource while the
        resource being locked.
        We also propose "X-Lock:" header field.

        It is assumed that the client and the server have some
        authentication functions. This document does not refer to it.

  3.1. LOCK/UNLOCK

        The LOCK method requests that the server lock the
        resource identified by the Request-URI.

        The UNLOCK method requests that the server cancel the
        lock status of the resource identified by the
        Request-URI.

        Only the user who has locked a resource can request PUT, POST,
        LOCK or UNLOCK to it. Any users, however, can always request
        GET, HEAD and LINK.

  3.2. X-Lock: header field

        The "X-Lock:" is a header in the server response that
        represents the information about locking status of a requested
        resource.
        When the client sends a GET, HEAD or LOCK request to the
        locked resource, the server returns the response including
        the "X-Lock:" header. Then, the client can show the
        information to the users. The followings are BNF and an
        example of this header.

        X-Lock = "X-Lock" ":" "user=" user_name ";" "date=" HTTP-date
        user_name = 1*8(ALPHA | DIGIT)

        ex.
        X-Lock: user="sekiya"; date="Thu, 15 Feb 1996 23:44:20 GMT"

4. Creation and modification of web resources via HTTP

  4.1. "X-PUT-Class" header field

        We propose "X-PUT-Class" header field for the PUT method.
        It specifies a type of a resource when the resource is
        created. The server decides how to handle to the resource
        according to the value of its field. The strings of "File",
        "Mkdir" or "VersionedFile" are allowed as its value. The value
        of the header field is stored as an attribute of the resource.
        BNF is as follows,

                PUT-Class = "X-PUT-Class" : PUT_type
                PUT_type = ("File" | "Mkdir" | "VersionedFile")

        The meaning of each values is as follows.

        - "File"
                The resource specified by the Request-URI is created
                as a normal file. The PUT request to this type of
                resource requests that the server overwrite the
                contents with the new entity.
        - "VersionedFile"
                The resource specified by the Request-URI is created
                as a versioned file. The PUT request to this type of
                an existing resource means that the server creates a
                new version of resource with the received entity.
        - "Mkdir"
                The resource specified by the Request-URI is created
                as an identifier of a collection of resources, such a
                directory, that manages the name for some resources
                under it.

5. Versioning

         We have decided our naming scheme based on the following:

        (1) accessibility from existing browsers (e.g. Netscape)
        (2) easy manipulation in existing directory-based file systems
                (e.g. UNIX file system)
        (3) ability of representing "composite" versions
                (e.g. version 2 of composite resource that consists of
                version 5 of X, a component resource, and version 3 of
                Y, another component resource)

  5.1. Naming Scheme

        A series of versions of a resource is identified by a unique
        directory name in a file system as a "representative"
        URL. Each version of a resource is placed under the directory
        and represented as follows:

                representative_URL "/" version_number

        For example, version 3 of
        "http://www.nttlabs.com/project1/x.html" is represented as
        follows:

                http://www.nttlabs.com/project1/x.html/3

        The latest version is referred by the representative URL and
        specific version can be referred by the representative URL +
        "/version_number". (Figure 1.)
         In this way, users can access any version by existing
        browsers and easily manipulate it in existing file systems.

  5.2. Versioning by using Link mechanism

         Each time a version of a resource has been revised, a new
        version is created and given a new URL based on the naming
        scheme described above.  In the same time, the original and
        new versions are linked bidirectionally with meta-level links.
        A link named "new" is established from the original to new
        versions and a link named "old" is established from the new to
        original versions.

        For example, Figure 1. illustrates links between
        versions of a resource (http://host/some/resource).


                        http://host/some/resource --------+
                                                          |
        ------------------------------------------------- | --------
                                                          |
                                                          V

             /1             /2             /3             /4
        +----------+   +----------+   +----------+   +----------+
        |+--------+|   |+--------+|   |+--------+|   |+--------+|
        ||  new   ||-->||  new   ||-->||  new   ||-->||  new   ||
        ||        ||<--||  old   ||<--||  old   ||<--||  old   ||
        |+--------+|   |+--------+|   |+--------+|   |+--------+|
        |+--------+|   |+--------+|   |+--------+|   |+--------+|
        ||        ||   ||        ||   ||        ||   ||        ||
        ||        ||   ||        ||   ||        ||   ||        ||
        ||        ||   ||        ||   ||        ||   ||        ||
        |+--------+|   |+--------+|   |+--------+|   |+--------+|
        +----------+   +----------+   +----------+   +----------+
                                                     latest version

                Figure 1. Links between versions of a resource


         A particular version of a resource can be transmitted via
        HTTP by specified by the "Content-Version:" field of HTTP
        headers, or according to the naming scheme when using existing
        clients. The following is an example of two type of
        specifying some version of a certain resource.

                http://www.nttlabs.com/project1/x.html/3
                        or
                http://www.nttlabs.com/project1/x.html
                Content-Version: "3"

  5.3. Examples of HTTP interactions

    5.3.1. Create a new resource

        [request]
                PUT http://server/path/resource
                        X-PUT-Class: VersionedFile
                (contents of initial version)

        [response]
                201 Created
                http://server/path/resource
                Content-Version: "1"

    5.3.2. Retrieve latest version

        [request]
                GET http://server/path/resource
                (Retreive the latest version automatically)

        [response]
                200 OK
                Content-Version: "5"
                Link: <http://server/path/resource/4>; rel="old"
                (contents of version 5)

    5.3.3. Retrieve a particular version

        [request]
                GET http://server/path/resource
                Content-Version: "3"

                  or
                GET http://server/path/resource/3

        [response]
                200 OK
                Content-Version: "3"
                Link: <http://server/path/resource/2>; rel="old"
                Link: <http://server/path/resource/4>; rel="new"
                (contents of version 3)

    5.3.4. Update an existing (versioned) resource

        [request]
                PUT http://server/path/resource
                (changed contents)

        [response]
                201 Created
                (Resource for new version are created, and establish
                links between created version and its new/old version)

References

[1] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk and T. Berners-Lee,
        "Hypertext Transfer Protocol -- HTTP/1.1,"
        Internet Draft, Work in Progress, August 1996

[2] E. J. Whitehead, Jr.,
        "Requirements on HTTP for Distributed Content Editing,"
        Internet Draft, Work in Progress, September 1996

[3] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource
        Locators (URL)." RFC 1738, CERN, Xerox PARC, University of
        Minnesota, December 1994.

Author Address

Kenji Ota
NTT Software Laboratories
250 Cambridge Avenue, #205
Palo Alto, CA 94306, USA
Email: ota@nttlabs.com

Kenji Takahashi
NTT Multimedia Communications Laboratories
250 Cambridge Avenue, #205
Palo Alto, CA 94306, USA
Email: kt@nttlabs.com

Kazuchika Sekiya
NTT Software Corporation
250 Cambridge Avenue, #205
Palo Alto, CA 94306, USA
Email: sekiya@ntts.com