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