Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

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 December 30, 2003.

Copyright Notice

Copyright (C) The Internet Society (2003). All Rights Reserved.

Abstract

This memo presents a technique for using XML (Extensible Markup Language) and HTTP (HyperText Transport Protocol) to edit content.

Table of Contents

1.  Introduction
2.  Terminology
3.  Motivation
4.  Scope
5.  The RESTLog Model
5.1  Creating a new Entry
5.2  Editing an entry
5.3  Deleting an entry
5.4  Discovery
6.  Functional Specification
6.1  Formats
6.1.1  RSS 2.0
6.1.2  RSD
6.1.3  Archive Format
6.2  Entry Points
6.2.1  Verbs
6.2.2  Result Codes
6.2.3  Content
7.  Security Considerations
§  References
§  Author's Address
§  Intellectual Property and Copyright Statements

1. Introduction

RESTLog is an application level protocol for publishing, and editing web resources. RESTLog unifies many disparate publishing mechanisms into a single, simple, extensible protocol. That protocol at it's core is the HTTP transport of an XML payload. There are only two XML vocabularies for the XML payloads, the RSS 2.0 XML format, and the RESTLog Archive Format.

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 [RFC2119].

3. Motivation

As of the writing of this specification there many different and competing specifications for editing a web-site, in particular protocols for editing weblogs. Some of those protocols include the Blogger API, the metaWeblog API, and .

The various implementations of the different APIs are all slightly different and even different implementations of the same API have issues. For example, quoted from the RSD specification: [http://archipelago.phrasewise.com/rsd]

Blogger has "plant.blogger.com", "api/RPC2", and the blogID. The "Path to Service" is case sensitive. If a user enters "/api/rpc2" in their preferences they get an error in html, courtesy of Tomcat, that states "The requested resource (/rpc2) is not available.". The error message is subject to change in format. This same problem could apply to every case.

Moveable Type uses an endpoint of "mt/mt-xmlrpc.cgi", and the domain level of the URL depends on the installation. The site identifier is the blogID number.

Manila and Radio use "rpc2", case insensitive. Manila's domain level URL depends on the installation but it does provide the "sitename" through the ManilaRPC API. Whew! Radio has a consistent siteID (as of this writing).

Conversant has its own API plus support for basic Blogger API. It uses x|x|x identifier where the various flexible elements of Conversant are "x". Familiarity with Conversant is somewhat required. These elements are also required when specifiying a message, so you need a message "number" that looks like this x|x|x|123. Path to service is rpc2, and case insensitive (not tested).

As you can imagine, plenty of folks have struggled to get this information exactly correct for each case. Anything that helps automate the process or gives users up to date information on the specific service their employing would help mitigate this difficulty.

Also, the above specifications are all based on XML-RPC, which is an RPC style protocol that doesn't have any accomodations for extensibility. RESTLog is a 'document' style protocol, where extensibility is enabled via the use of xml namespaces.

4. Scope

This document covers the transfer of RSS 2.0 and RESTLog Archive formatted XML Payloads to accomplish the specific tasks of creating a new weblog post, and editing an old weblog post. This specification also covers the RESTLog Archive Format, but defers to @@XXXX@@, which specifies the RSS 2.0 format.

The protocol is defined primarily to allow remote editing of content on a weblog. The protocol is restricted to editing Entries in a weblog and does not cover editing templates, images, blogrolls, etc.

5. The RESTLog Model

The entry point to start editing any weblog with the RESTLog API is a set of two URIs. These two URIs, which we shall refer to as "createURI", and "archiveURI", are used for, respectively, creating a new entry and getting a list of the all the Entries on a site. Each of these URI's support some of the HTTP verbs. For example, to create a new Entry, an RSS Item fragment is POSTed to "createURI". The minimum set of verbs that each interface must support is specified. Other HTTP verbs may be supported by each URI, this specification is only concerned with the verbs that must be present, and does not restrict the supported verbs to just those specified. Also note that the URL's used for RESTLog editing need bear no relation to the URIs used to access the HTML version of the content.

To get a list of Entries that already exist, the client does a GET on the "archiveURI". The list of Entries returned may be sufficient for the user, or further retrievals may be required to get the Entries the user is trying to manipulate, see the RESTLog Archive Format for more details, particularly the "more" element.

5.1 Creating a new Entry

To create a new Entry on the server, the client POSTs an Entry to the "createURI". For example, if "createURI" were "http://example.com/news", the headers and body of the HTTP request to "example.org" would look like:

This would create a new weblog Entry with title "My First Post".

5.2 Editing an entry

To begin the editing process, the URI of the RSS 2.0 item fragment representating the Entry must be found. The "archiveURI" is the place to begin that discovery process, by doing a GET on that URI. The content returned from that request will be an XML document in the RESTLog Archive Format.

For example, if "archiveURI" were "http://example.com/archive", the headers and body of the HTTP request to "example.org" would look like:

This would return a list of some of the Entrys on the weblog.

The response from such a request would look like:

This would return a list of some of the Entrys on the weblog.

Now the Entry that the user is looking for may not be in the list and they may need to go further into the archive. For example, if they knew they wanted to edit a Tech Entry that didn't appear in the "Last 10 Entries", then they would retrieve the Archive document that resides at "http://sample.org/archive/technology", which could contain some or all of the Entries in the Tech category. Note that the document at "http://sample.org/archive/technology" could also contain additional "more" elements.

The use of multiple GET's and traversing a web of links allows the server to present the Entries in multiple ways to the user. One alternative to this would be to present a single long list of Entries, maybe with attributes attached. That might be useful, but the document could get quite long and cumbersome to transfer. It also puts the effort onto the RESTLog client to sort, categorize and display the contents of the archive. In addition, adding new attributes would require an update to the client software to take advantage of the new information.

Another approach would be to allow a query syntax that allowed searching for Entries based on Date or keyword. The downfall of this approach is the same, in that the addition of new seach parameters requiring updating the client software.

Once a resource has been chosen the client can do a GET on that resource to get an RSS 2.0 formatted representation of that Entry. Editing of the content or other elements takes place, then the client PUT's the modified Entry back to the same URI to update the Entry.

5.3 Deleting an entry

Once a resource has been chosen the client can do a DELETE on that resource to delete the Entry.

5.4 Discovery

RSD is used as the format to hold both the "createURI" and the "archviveURI". When editing a web site, the RSD file needs to be found before editing can begin. Part of the RSD specification is for Auto-Discovery, the addition of an HTML 'link' tag to a web page that contains the URI of the RSD file. Please see the @@external link?@@ RSD Specification for more details.

@@ What about WSIL? @@

None.

6. Functional Specification

6.1 Formats

6.1.1 RSS 2.0

None.

6.1.2 RSD

None.

6.1.3 Archive Format

None.

None.

6.2 Entry Points

6.2.1 Verbs

None.

6.2.2 Result Codes

None.

6.2.3 Content

None.

None.

7. Security Considerations

None.

References

Author's Address

Intellectual Property Statement

The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director.

Full Copyright Statement

Copyright (C) The Internet Society (2003). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees.

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

Funding for the RFC Editor function is currently provided by the Internet Society.