| Network Working Group | J.C. Gregorio |
| INTERNET DRAFT | BitWorking, Inc |
| <draft-gregorio-04.html> | July 2003 |
| Category: Standards Track | |
| Expires: January 2004 |
The EchoAPI
draft-gregorio-04.html
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 in January 2004.
Copyright (C) The Internet Society (2003). All Rights Reserved.
This memo presents a technique for using XML (Extensible Markup Language) and HTTP (HyperText Transport Protocol) to edit content.
To provide feedback on this draft RFC please visit the Echo Wiki.
1
Introduction
2
Terminology
3
Scope
4
The EchoAPI Model
4.1
Introspection
4.1.1
Introspection Discovery
4.2
Creating a new Entry request
4.2.1
Retrieving an Entry
4.3
Editing an entry
4.4
Deleting an entry
4.5
Finding an entry
4.6
Editing User Prefs
4.7
Adding Comments
4.7.1
Comment Auto-Discovery
4.7.1.1
HTML Auto-Discovery
4.7.1.2
Echo Feed Auto-Discovery
5
Functional Specification
5.1
Formats
5.2
Actions
5.2.1
Create Entry
5.2.2
Edit Entry
5.2.3
Delete Entry
5.2.4
Get List of Entries
5.2.5
Get User Info
5.2.6
Set User Info
5.2.7
Get Categories
5.2.8
Set Categories
5.2.9
Result Codes
5.2.10
Content
6
Security Considerations
7
Revision History
§
References
§
Author's Address
§
Intellectual Property and Copyright Statements
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.
To provide feedback on this draft RFC please visit the Echo Wiki.
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.
<?xml version="1.0" encoding='iso-8859-1'?> <introspection xmlns="http://example.com/newformat#" > <edit-entry>http://example.org/reilly/</edit-entry> <user-prefs>http://example.org/reilly/prefs</user-prefs> <search-entries>http://example.org/reilly/search</search-entries> </introspection>
Each element in <introspection> represents a single facet of the EchoAPI. While a site must fully support each facet they list in their introspection file, a site does not need to support all the facets in this RFC. Additionally, new facets may be added either through vendor extension or follow-on RFCs. This first example site furnishes only a minimal set of functionality. A more full featured site might return:
<?xml version="1.0" encoding='iso-8859-1'?> <introspection xmlns="http://example.com/newformat#" > <edit-entry>http://example.org/reilly/</edit-entry> <user-prefs>http://example.org/reilly/prefs</user-prefs> <search-entries>http://example.org/reilly/search</search-entries> <edit-template>http://example.org/reilly/templates</edit-template> <categories>http://example.org/reilly/categories</categories> </introspection>
This particular introspection file for http://example.org/reilly 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://dev.example.net/api?userid=reilly&action=edit
The URI of the Introspection file is discovered using RSD. RSD, which stands for Really Simple Discovery, is used for automatic discovery of supported editing APIs.
Here is an RSD file for the website at http://example.org/reilly.
<?xml version="1.0" ?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd" >
<service>
<engineName>EchoAPI</engineName>
<engineLink>http://purl.org/Echo/API</engineLink>
<homePageLink>http://example.org/reilly</homePageLink>
<apis>
<api name="EchoAPI" preferred="true"
apiLink="http://example.org/reilly/introspection"
blogID="">
</api>
</apis>
</service>
</rsd>
Note that RSD also specifies the inclusion of a <link> tag included in the header of the website homepage, to aid in discovery of the RSD file.
HTTP POST is used for content creation. The new content is formatted as an Echo Entry and then POSTed to the URI given in the <edit-entry/> element of the Introspection file. Note that the Entry below does not have an <id> element, and that is used to differentiate between creating a new Entry and updating an old Entry.
To create a new Entry on the site the client connects to port 80 on http://example.org and sends:
POST /reilly HTTP/1.1
Content-Type: application/not-echo+xml
<?xml version="1.0" encoding='iso-8859-1'?>
<entry xmlns="http://example.com/newformat#" >
<title>My First Entry</title>
<subtitle>In which a newbie learns to blog...</subtitle>
<summary>A very boring entry...</summary>
<author>
<name>Bob B. Bobbington</name>
<homepage>http://bob.name/</homepage>
<weblog>http://bob.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">Hello, <em>weblog</em> world! 2 < 4!</p>
</content>
</entry>
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:
HTTP/1.1 201 Created Location: http://example.org/reilly/1
The URI of the filled in Entry is returned via the HTTP headers. If a GET is done on the URI then a filled in Entry would be returned, including the elements <link/>, <id/>, <created/> and <modified/>.
To retreive the new Entry on the site the client needs to know the URI of the Echo Entry. This URI is obtained either by the HTTP Location header returned during the creation of the Entry as outlined in section 4.2, or it is discovered by the search interface discussed in section 4.5.
For the newly created Echo Entry above, the client connects to port 80 on http://example.org and sends:
GET /reilly/1 HTTP/1.1 Accept: application/not-echo+xml
This would retrieve the Entry just created.
The response might look like:
HTTP/1.1 200 Ok
Content-Type: application/not-echo+xml
<?xml version="1.0" encoding='iso-8859-1'?>
<entry xmlns="http://example.com/newformat#" >
<title>My First Entry</title>
<subtitle>In which a newbie learns to blog...</subtitle>
<summary>A very boring entry...</summary>
<author>
<name>Bob B. Bobbington</name>
<homepage>http://bob.name/</homepage>
<weblog>http://bob.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<created>2003-02-05T14:10:58Z</created>
<modified>2003-02-05T14:10:58Z</modified>
<link>http://example.org/reilly/2003/02/05#My_First_Entry</link>
<id>urn:example.org:reilly:1</id>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">Hello, <em>weblog</em> world! 2 < 4!</p>
</content>
</entry>
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. The modified Echo Entry is POSTed to the same URI used to create an entry, that is, the URI stored in the <edit-entry/> element of the Introspection file.
If the <content/> element is updated the transaction might look like:
POST /reilly HTTP/1.1
Content-Type: application/not-echo+xml
<?xml version="1.0" encoding='iso-8859-1'?>
<entry xmlns="http://example.com/newformat#" >
<title>My First Entry</title>
<subtitle>In which a newbie learns to blog...</subtitle>
<summary>A very boring entry...</summary>
<author>
<name>Bob B. Bobbington</name>
<homepage>http://bob.name/</homepage>
<weblog>http://bob.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<created>2003-02-05T14:10:58Z</created>
<modified>2003-02-05T14:10:58Z</modified>
<link>http://example.org/reilly/2003/02/05#My_First_Entry</link>
<id>urn:example.org:reilly:1</id>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">A big hello to the
<em>weblog</em> world! 2 < 4!</p>
</content>
</entry>
The server knows this is an update instead of creation from the existence of the <id/> element.
The response from the server, on success, returns a 205 HTTP status code.
HTTP/1.1 205 Reset Content
The <content/> element now reflects the updated content, and the <modifed/> element has been updated to reflect when the change was made.
As was done after creation, a GET to the URI of the Echo Entry would return the modified Entry.
To retreive the modified Entry the client connects to port 80 on http://example.org and sends:
GET /reilly/1 HTTP/1.1 Content-Type: application/not-echo+xml
This would retrieve the recently modified Entry.
The response might look like:
HTTP/1.1 200 Ok
Content-Type: application/not-echo+xml
<?xml version="1.0" encoding='iso-8859-1'?>
<entry xmlns="http://example.com/newformat#" >
<title>My First Entry</title>
<subtitle>In which a newbie learns to blog...</subtitle>
<summary>A very boring entry...</summary>
<author>
<name>Bob B. Bobbington</name>
<homepage>http://bob.name/</homepage>
<weblog>http://bob.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<created>2003-02-05T14:10:58Z</created>
<modified>2003-02-05T14:22:03Z</modified>
<link>http://example.org/reilly/2003/02/05#My_First_Entry</link>
<id>urn:example.org:reilly:1</id>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">A big hello to the
<em>weblog</em> world! 2 < 4!</p>
</content>
</entry>
The <content/> element now reflects the updated content, and the <modifed/> element has been updated to reflect when the change was made.
Deleting an Entry uses the URI of the Echo Entry. This is the same URI the client does a GET on to retrieve the Echo Entry.
For example, to delete the first Entry in our example the client connects to port 80 on the server and sends:
DELETE /reilly/1 HTTP/1.1
The response from the server upon a successful deletion is:
HTTP/1.1 200 Ok
Finding an Entry uses the 'search-entries' URI from the Introspection file. For the example Introspection file given, that is the URI http://example.org/reilly/search. The search parameters given are used to select which Entries are listed in the response.
For example, to retrieve the locations of the last 20 Entries, the client connects to port 80 on the server and sends:
GET /reilly/search?last=20 HTTP/1.1 Accept: application/not-echo+xml
The server searches for Entries that match the criteria and returns a response that lists those matches.
The response from the server might look like:
HTTP/1.1 200 Ok Content-Type: application/not-echo+xml <search-results xmlns="http://example.com/newformat#" > <match title="My First Post">http://example.org/reilly/1</match> <match title="My Second Post">http://example.org/reilly/2</match> </search-results>
There will be one <match/> element for every Entry that matches the given criteria. Each <match/> element contains the URI of an Entry and an attribute 'title' which contains the title of the Entry. If the client needs the Echo Entry then it performs an HTTP GET on the given URI as outlined in section 4.2.1.
There are other search critera that can be added. For example the 'all' parameter, if present, requests that the server return a list of all Entries on the site. Other additional parameters that can be added are 'start-range' and 'endRange'. Access to the entries is by an index, with the first Entry having an index number of 0.
For example, this request will return a list of all Entries from index 2 to index 27.
POST /reilly/search?start-range=2&end-range=27 HTTP/1.1
The rest of the search parameters and their properties are covered in detail in section 5.1.
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 the website at http://example.org/reilly, the request would look like:
GET /reilly/prefs HTTP/1.1
This would return a list of user configuration parameters and their values.
The reponse would look like:
HTTP/1.1 200 OK Content-Type: application/not-echo+xml <?xml version="1.0" encoding='iso-8859-1'?> <userprefs xmlns="http://example.com/newformat#" > <name>Reilly</name> <id>1234</id> <email>reilly@example.org</email> </userprefs>
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 sputnik@example.org, we would then POST back to the 'user-prefs' URI:
POST /reilly/prefs HTTP/1.1 Content-Type: application/not-echo+xml <?xml version="1.0" encoding='iso-8859-1'?> <userprefs xmlns="http://example.com/newformat#" > <name>Reilly</name> <id>1234</id> <email>sputnik@example.org</email> </userprefs>
Assuming the update goes successfully, the updated user preferences will be returned in the response.
The reponse would look like:
HTTP/1.1 200 OK Content-Type: application/not-echo+xml <?xml version="1.0" encoding='iso-8859-1'?> <userprefs xmlns="http://example.com/newformat#" > <name>Reilly</name> <id>1234</id> <email>sputnik@example.org</email> </userprefs>
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 systems for adding comment-like information to an Entry. 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/comments" 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:
POST /reilly/1/comments HTTP/1.1
Content-Type: application/not-echo/xml
<entry xmlns="http://example.com/newformat#" >
<title>My Comment</title>
<author>
<name>Fred F. Fobbington</name>
<homepage>http://fred.name/</homepage>
<weblog>http://fred.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">Welcome to the neighborhood!</p>
</content>
</entry>
This would create a new comment 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:
HTTP/1.1 201 Created
Content-Type: application/not-echo+xml
<entry xmlns="http://example.com/newformat#" >
<title>My Comment</title>
<author>
<name>Fred F. Fobbington</name>
<homepage>http://fred.name/</homepage>
<weblog>http://fred.blog/</weblog>
</author>
<issued>2003-02-05T12:29:29</issued>
<created>2003-02-05T14:20:12Z</created>
<modified>2003-02-05T14:20:12Z</modified>
<link>http://example.org/reilly/2003/02/05#comment1</link>
<id>urn:example.org:reilly:1:1</id>
<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">Welcome to the neighborhood!</p>
</content>
</entry>
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:
<link rel="service.comment" type="application/not-echo+xml"
href="url goes here" title="EchoComment">
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 a <comment/> element in each Entry that is used to provide the location of the URI that accepts comment POSTs. 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.
15Jul2003 - Updated the RSD version used from 0.7 to 1.0. Change the method of deleting an Entry from POSTing <delete/> to using the HTTP DELETE verb. Also changed the query interface to GET instead of POST. Moved Introspection Discovery to be up under Introspection.
10Jul2003 - Added a link to the Wiki near the front of the document. Added a section on finding an Entry. Retrieving an Entry now broken out into it's own section. Changed the HTTP status code for a successful editing of an Entry to 205.
7Jul2003 - Entries are no longer returned from POSTs, instead they are retrieved via GET. Cleaned up figure titles, as they are rendered poorly in HTML. All content-types have been changed to application/not-echo+xml.
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] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| Joe Gregorio | |
| BitWorking, Inc | |
| 1002 Heathwood Dairy Rd. |
|
| Apex, NC 27502 | |
| US | |
| Phone: | +1 919 272 3764 |
| EMail: | joe@bitworking.com |
| URI: | http://bitworking.com/ |
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.
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.
Funding for the RFC editor function is currently provided by the Internet Society.