]> The EchoAPI BitWorking, Inc
1002 Heathwood Dairy Rd. Apex NC 27502 US +1 919 272 3764 joe@bitworking.com http://bitworking.com/
This memo presents a technique for using XML (Extensible Markup Language) and HTTP (HyperText Transport Protocol) to edit content.
EchoAPI is an application level protocol for publishing, and editing web resources. EchoAPI unifies many disparate publishing mechanisms into a single, simple, extensible protocol. The protocol at its core is the HTTP transport of an XML payload.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",the and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
This document covers the editing of content of a periodically updating website using the HTTP and XML. Many of the XML payloads are in Echo format, which will not be documented here. This specification will mirror some of the functionality of the Blogger 2.0 API, which includes support for the Server Introspection API.
When editing the content of the website http://example.org/reilly, the first thing to do is find out the servers capabilites. Each server may only implement a subset of this specification, and the 'introspection' file lists all the functions that each site supports. This mirrors the Server Introspection API used by the Blogger 2.0 API.
http://example.org/reilly/ http://example.org/reilly/prefs ]]>
This site furnishes only a minimal set of functionality. A more full featured site might return: http://example.org/reilly/ http://example.org/reilly/prefs http://example.org/reilly/templates http://example.org/reilly/categories ]]>
Where to store the introspection file on the web and how to make the URI of the introspection file easy to find will be discussed later. This particular introspection file for http://example.org/rielly tells us that the EchoAPI implementation supports both the 'edit-entry' and the 'user-prefs' interfaces, and it also specifies the URIs to use for each of these interfaces. Note that the example URIs given are not normative, nor are there any constraints on the URIs that can be specified. The 'edit-entry' URI could just have easily been:
HTTP POST is used for content creation. The new content is formatted as an Echo Entry and then POST'd to the URI given in the 'edit-entry' element of the introspection file.
To create a new Entry on the site the client connects to port 80 on http://example.org and sends: My First Entry In which a newbie learns to blog... A very boring entry... Bob B. Bobbington http://bob.name/ http://bob.blog/ 2003-02-05T12:29:29

Hello, weblog world! 2 < 4!

 ]]> This would create a new weblog Entry with the title "My First Entry".
Assuming everything goes well and the Entry is created, the response might look like: My First Entry In which a newbie learns to blog... A very boring entry... Bob B. Bobbington http://bob.name/ http://bob.blog/ 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:10:58Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

Hello, weblog world! 2 < 4!

 ]]> Information has been added to the Entry, including the 'link', 'id', 'created' and 'modified' elements.
@@ Editors Note: Beware the Echo syntax is still in flux and the above example is not normative. @@
Editing an Entry is the same as creating one, the difference is that the Entry you POST already has 'id' filled in. HTTP POST the modified Echo Entry to the same URI used to create an entry, the URI stored in the 'create-entry' element of the introspection file.
If we update our content element and POST it, the transaction looks like: My First Entry In which a newbie learns to blog... A very boring entry... Bob B. Bobbington http://bob.name/ http://bob.blog/ 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:10:58Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

A big hello to the weblog world! 2 < 4!

 ]]> The server knows this is an update instead of creation from the existence of the 'id' element.
The response from the server is the same, on success returning a filled in Entry: My First Entry In which a newbie learns to blog... A very boring entry... Bob B. Bobbington http://bob.name/ http://bob.blog/ 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:20:03Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

A big hello to the weblog world! 2 < 4!

 ]]> The 'content' element now reflects the updated content, and the 'modifed' element has been updated to reflect when the change was made.
How to retrieve the Echo formatted Entry is not covered at this time.
Deleting an Entry also uses the same 'edit-entry' URI.
You POST to the 'edit-entry' URI the body: ]]> The POST handler on the server side uses the value of the 'id' attribute to determine which Entry to delete.
The response from the server upon a successful deletion is:
The preferences for the user are edited through the URI supplied in the 'user-prefs' element of the introspection file. To retrieve the current user preferences issue and HTTP GET on the URI.
For our website at http://example.org/reilly, the request would look like: This would return a list of user configuration parameters and their values.
The reponse would look like: Reilly 1234 reilly@example.org ]]> The values can then be updated, and doing an HTTP POST of the updated file back to the 'user-prefs' URI will update the user preferences.
For example, if we update our email address, from reilly@example.org to mr_reilly@example.org, we would then POST back to the 'user-prefs' URI: Reilly 1234 mr_reilly@example.org ]]> Assuming the update goes successfully, the updated user preferences will be returned in the response.
The reponse would look like: Reilly 1234 my_reilly@example.org ]]>
This part of the EchoAPI does not use the URIs listed in the 'introspection' file. There are different interfaces now circulating for an TrackBack, Ping-Back, Post-It. All of these are a way of commenting on an item. The only thing missing from the mix is a way to do "comments" themselves. This section of the specification is intended to be a roll-up of all the above specifications and to cover comments as well. Creating a comment is similar to creating an Entry, that is, you HTTP POST an Entry to a URI. For now we will defer discussing how to obtain the corrent URI to POST to.
For example, if "http://example.org/reilly/1" is the URI that accepts comments for the first Entry on the website http://example.org/reilly, then the client would open port 80 on example.org and send: My Comment Fred F. Fobbington http://fred.name/ http://fred.blog/ 2003-02-05T12:29:29

Welcome to the neighborhood!

 ]]> This would create a new comment/trackback for the first Entry on "http://example.org/reilly".
The response to this POST, assuming everything went without error, is a filled in Echo Entry, and would look like this: My Comment Fred F. Fobbington http://fred.name/ http://fred.blog/ 2003-02-05T12:29:29 2003-02-05T14:20:12Z 2003-02-05T14:20:12Z http://example.org/reilly/2003/02/05#comment1 urn:example.org:reilly:1:1

Welcome to the neighborhood!

 ]]> This would create a new comment/trackback for the first Entry on "http://example.org/reilly".
Two mechanisms are available for discovering the URI that you would use to create a comment. The first is a way to put that information in HTML, the second is a way to embed that information in an Echo feed.
The <link> element has been successful in finding RSS feeds and is appropriate to use here for discovering the "commentURI" in HTML pages. The <link> tag goes in the <head> section of an HTML page and is used to indicate a document relationship. For a similar example of using the link tag to discover a URI, refer to the usage of of the link tag for RSS Auto-Discovery. In this case the form of the link tag used to indicate the location of the comment URI is:
]]>
Where href should be set to the URI that accepts POSTs for comments. Applications looking for a URI to post comments to need to parse out the headers of the web page and look for a link tag that has a relation rel of "comment" and a mime-type of "application/not-echo+xml".
There is an item level element named 'comment' in Echo that is used to provide the location of the "commentURI" endpoint to aggregator software. This is providing the same information as the link tag does in HTML. @@ No example yet. Needs to be specified. @@
@@ TBD @@ More formal specification of all the XML formats used in this protocol.
@@ TBD @@ A more formal specification of all the actions.
None.
None.
None.
None.
None.
None.
None.
None.
@@TBD@@ Mostly 200 for normal responses, seems that 30X codes for redirects are useful but might make implementations a little harder to implement. @@Ref CommentAPI problems returning a 303 vs 200@@
@@TBD@@ How does an Echo document change when used in these different contexts? Which parts that are required when found in a feed become optional when used in creating an Entry?
@@TBD@@ Talk here about using HTTP basic and digest authentication. @@TBD@@ Talk here about denial of service attacks using large XML files, or the billion laughs DTD attack.
5Jul2003 - Renamed from EchoAPI.html to follow the more commonly used format: draft-gregorio-NN.html. Renamed all references to URL to URI. Broke out introspection into it's own section. Added the Revision History section. Added more to the warning that the example URIs are not normative.
&rfc2119;