UserPreferences

EchoApiChangeLog


API Change Log

Differences from version 6 to 7:

  1. Removed the use of the RSD file for auto-discovery.

  2. Changed copyright until a final standards body is chosen.

  3. Changed query parameters for the search facet to all begin with atom- to avoid name collisions.

  4. Updated all the Entries to follow the 0.2 version.

  5. Changed the format of the search results and template file to a pure element based syntax.

Differences from version 5 to 6:

  1. Added template editing interface.

  2. Moved to PUT for updating Entries.

  3. Changed all the mime-types to application/x.atom+xml.

  4. Changed 'edit-entry' to 'create-entry' in the Introspection file to more accurately reflect it's purpose.

Differences from version 4 to 5:

  1. Renamed everything Echo to Atom.

  2. Added version numbers in the Revision history.

  3. Changed all the mime-types to application/atom+xml.

Differences from version 3 to 4:

  1. Updated the RSD version from 0.7 to 1.0.

  2. Change the method of deleting an Entry from POSTing <delete/> to using the HTTP DELETE verb.

  3. Changed the query interface to GET instead of POST.

  4. Moved Introspection Discovery to be up under Introspection.

  5. Introduced the term 'facet' for the services listed in the Introspection file.

Duly Noted Improvements

Here are the parts of RestEchoApiDiscuss that have been incorporated into a draft of the API.

Thanks to everyone who suggest improvements in the API! The following are comments made here which have been incorporated (or not) into the subsequent drafts of the RFC

Into Version 0.2

[TimBray RefactorOk] (section 4.2) I think there's no point in returning the full text of an entry along with the code 201 when you create it; just return the URI of the newly-created entry. Same for the update transaction in section 4.3.

[TimBray RefactorOk] (section 4.4) text/xml is evil, blecch, don't use it. Use app/not-echo+xml throughout please.

[AdamKeys RefactorOk] The Content-type is application/not-echo+xml in some places and text/xml in other places. Is there a reason for this?

Are the text/xml methods not specified by Echo?

[AaronSw] Querying for entries is sorely missing.

[TimBray] I suggest that when you successfully edit an existing entry via POST (section 4.2), you return 205 Reset Content. Also, you don't need to echo the new version of the message, the return body can be empty. Same for the delete transaction (4.3).

[TimBray] General comment: URI not URL throughout. URL no longer has a normative reference and stands only for Universal Republic of Love.

[MarkPilgrim] Many weblogs support autodiscovery of supported posting APIs through DanielBerlinger's ReallySimpleDiscoverability (RSD). Movable Type comes with an RSD template by default, and there's a LINK tag in the home page template that points to it. The point is that end users enter their home page, and a blogging app like NetNewsWire or KungLog can get the address of the RSD file, then get info about which posting APIs are supported. Recommend we support this, standardize on what to put in the RSD file, and what it points to. (Should probably point to the introspection file.)

Into Version 0.3

The search mechanism in the current draft is crazy. Searches should be GETs, not POSTs, and there's no reason to create new XML formats for them.

Here's my proposal:

Say query-entries is "/reilly/search?" (it could also be "/mt/mt.cgi?mode=rss&") then:

GET /reilly/search?last=5

gets a <feed> with the last five entries in it.

GET /reilly/search?since=2003-02-05T14:22:03Z

gets all the entries modified since that date (or maybe just the 20 most recent). I don't see the use case for ranges, so I don't describe them here but they'd be easy to implement.

Note that what's returned is the full entry, not just the title. I can see why you might only want a subset of the information (to populate a display for the user to choose from, say) but I don't see why title is the only subset you want (you might want the display to be color-coded by category or age) and it doesn't seem worthwhile to provide a whole subsetting mechanism when bandwidth is relatively cheap here. [AaronSw]

+1 [DannyAyers]


[AaronSw] Discovery should go first, since that'll be the first thing a client app does.

Into Version 0.6

[ZhangYining] Regarding version 0.5, adding an entry (original) returns only the id, but adding a comment returns the complete comment entry? Is there a compelling reason for this difference, or did I miss something here?

[SeairthJacobs] Regarding version 0.5, shouldn't the mime type be "application/x.atom+xml"? An application should handle both variants, just in case, but until the new mime type is actually registered, shouldn't the "x." convention be used?

What's the overall pattern to the RESTful API? We can state at the top of the interface document what the general style of all the APIs are. Once the pattern is set, any particular usage of the pattern is just clarifying that usage (entries, prefs, comments, templates, graphics). Correspondingly, once the pattern is given, any issues with implementation of the pattern can be addressed to the pattern and reflected in all usages, including fallback techniques and mappings to XmlRpc and SOAP.

Using the common HTTP verbs provides a pattern for working with all resources:

Note the difference between POST and PUT for creating new entries. Some tools create IDs dynamically for new entries (use POST) some tools use a user-provided name as an ID (use PUT). Introspection should indicate which style the tool supports. Note also that even tools that support PUT for named entries will often use POST for dynamically named comments.

Feeds: GET.
Site pages: GET. Browser-readable pages displayed on the site.
Entries: POST, PUT, GET, DELETE.
Comments: POST, sometimes PUT, usually GET (but not often individually), rarely DELETE except by site owner.
Prefs: PUT, GET.
Templates: PUT, GET -- both sometimes only to pre-defined names, others can use any names. The latter support DELETE.
Static data: images, audio, video, style sheets, javascript and other static files: PUT, GET, DELETE. Some publishing tools don't support arbitrary files. Some support subdirectories.

Question: Should templates be handled by this interface?

Question: How are templates handled?

[MikeDavies] (RefactorOk DeleteOk MoveOk) More of a REST question than a RestEcho question: From Joe's example of a POST request it suggests its using HTTP/1.1 . AIUI HTTP/1.1 requires a Host: www.example.com parameter (so allowing multihomed websites). Also for a POST request, should there be a Content-Length parameter? I'm trying to write a .php page running under Apache to handle incoming necho REST POST request, but Apache is borking without the Content-Length (Treats the entity header and the entity body as if there were two header requests) .

Into Version 0.7


The responses from "Finding an entry" and "Editing Templates" should follow the Syntax Schema Patterns. Specifically, it should be noted that <search-results> and <templates> are [should be] themselves "Entity" elements and can have properties besides just their results (like options used or features supported).

<match> should be <entry>, using a subset ("search profile") of entry properties. <id> is used below as "the editing URI" (as returned in 'Location:' after POSTing), but that is not currently defined. "Finding an entry" has significant overlap with AggregatorApi and maybe should be done that way.

<search-results xmlns="http://example.com/newformat#">
  <foo:skippedDeleted>true</foo:skippedDeleted>
  <entry>
    <title>My First Post</title>
    <id>http://example.org/reilly/1</id>
  </entry>
  <entry>
    <title>My Second Post</title>
    <id>http://example.org/reilly/2</id>
  </entry>
</search-results>

<templates> and <template> are specific types of resources, publishing systems may have other types of standard resources and it should be considered whether to use per-type schema entities or generic entities where possible, just allowing the "type" to be keyed off of the URI requested, like the <edit-template> URI. The following example uses a generic entity name for resources and also the Syntax Schema Pattern.

GET /reilly/templates HTTP/1.1
Accept: application/x.atom+xml
<resources xmlns="http://example.com/newformat#" >
  <foo:dynamicTemplatesSupported>true</foo:dynamicTemplatesSupported>
  <resource>
    <title>Main</title>
    <id>http://example.org/tpl/Main.html</id>
  </resource>
  <resource>
    <title>Story</title>
    <id>http://example.org/tpl/Stry.html</id>
  </resource>
  <resource>
    <title>Feed</title>
    <id>http://example.org/tpl/Feed.xml</id>
  </resource>
</resources>


[ZhangYining] Possible typo in Section 5.6 Editing User Prefs, which says "...we would then POST back to the 'user-prefs' URI:", however the example given uses PUT ;-)


[JamesAylett] Section 5.5 has mismatching styles in the suggestion for range querying of entries: start-range vs endRange. This is in the paragraph description, but not in the example (which uses end-range).


[AnswerMe] Is using ReallySimpleDiscoverability (RSD) to get the Introspection file to round-trippy and should the Introspection be discoverable via it's own link tag.


[JonathanSmith] These Internet Drafts that Joe is producing have an InternetSociety copyright. How does the ISOC copyright relate to issues of Intellectual Property mentioned in ProjectLegal or License issues?

Into Version 0.8

Question: Will TrackBack be incoporated into the API, or left as an extension to the API?

Answer: Yes. Likely, TrackBack, comments, PingBack and similar could all be folded into one comment API.


Incorporated Somewhere else

[DannyAyers, RefactorOk] Nice piece of work, especially with it being IETF style. Does it seem to treat the PieApi in isolation from the rest of the language and does this sidestep some of the benefits of being able to look at the system together? (next bit extracted from [WWW]this comment) In particular, can there be a common set of XML elements and different sets of them used in different circumstances - so an API delete POST would only need the postID element plus authentication elements (encrypted please!), a full post to the API would include everything from the syndication feed profile plus authentication elements? The sets of elements can be seen in the ProfileMatrix.

If the same XML format is used throughout, then it should be possible to take the bulk of the XML message and store it unchanged to pass back as part of the syndicated feed. This could allow for a server-side Really Simple Implementation (RSI).

Not Incorporated

The following comments were NOT incorporated into the draft RFC

[NickChalko RefactorOk] The /reilly/prefs URL takes up the name of a post or category. prefs becomes a reserved word. Since it is likely there will be a need for other reserved words, would it be better to use /reilly/system/prefs and /reilly/system/other_reserved_word

[TimBray] For posting comments, why not use the same URI that's used for editing, just as you do for deleting? Then you can just do

<comment id="URI of entry being commented on">
  <entry>
   ...
  </entry>
 </comment>
You could have some optional trackback-like fields identifying the source of the comment.

[JustinErenkrantz RefactorOk] What I think is missing from this REST-ish proposal is how to deal with aggregation of the stories and allowing for multiple representations of a resource. Using a REST-centric approach, I believe aggregation can be done cleanly via collections. For example, if RestEchoApiOneUriForEachEntry is held to be true (as I believe should be because it is fairly RESTful), then a 'story' could have a URI of /weblog/2003/7/5/1 (1 would be the daily unique identifier for this particular weblog - the initial PUT/POST would create that unique identifier - it could be granular at the hour level, minute, etc...). Then, in order to retrieve all stories in a given month, you could GET /weblog/2003/7/ or, for a year, GET /weblog/2003/. Now, to put a spin on this that I've used before in REST-centric implementations - GET /weblog/2003/7/5/1.html. (The extension could theoretically be replaced with paths - 1/html). This would retrieve an HTML version of the content specified in that Echo post. We can really start to leverage the ability to morph the representation of that resource accordingly. This implies that the complete [content] will be included in the Echo posting (rather than a summary). We can also handle GracefulDegradation in this manner. An 'RSS 2.0-compliant' client could retrieve /weblog/2003/7/5/1.rss - the Echo module could then translate into RSS 2.0 as desired. And, HTML browsers would use this same interface to view the pages. A thought...

[EmmanuelDecarie RefactorOk, DeleteOk] Does it make sense when getting the server capabilities to have an element that tell if the server support some forms of rpc, like XML-RPC for echo, SOAP for echo, or even the MetaWeblogAPI or the Blogger API? For exemple:

<introspection> 

  <rpc>

    <echoxmlrpc>http://example.org/reilly/echoxmlrpc</echoxmlrpc>

    <echosoap>http://example.org/reilly/echosoap</echosoap>

    <metawebloapi>http://example.org/reilly/metawebloapi</metaweblogapi>

    <bloggerapi>http://example.org/reilly/bloggerapi</bloggerapi>

  </rpc>

</introspection> 
or
<introspection> 

  <rpc api='echoxmlrpc'>http://example.org/reilly/echoxmlrpc</rpc>

  <rpc api='echosoap'>http://example.org/reilly/echosoap</rpc>

  <rpc api='metawebloapi'>http://example.org/reilly/metawebloapi</rpc>

  <rpc api='bloggerapi'>http://example.org/reilly/bloggerapi</rpc>

</introspection> 

[JimRoepcke] Could the prefix for query parameters be changed to atom_, instead of the current atom-? Some systems can marshall query parameters directly as parameters to handling subroutines, but "-" is not a valid character for identifiers (variables/parameters) in nearly every programming language. Using atom_foo instead of atom-foo will make integration much easier for such systems.

*The search interface was removed in Rev 08.*

[ChristianMogensen] Suggest you change http://example.com/newformat to http://tempuri.org/newformat to more clearly separate the placeholder ATOM namespace URI from the example ones (which won't need to change after ATOM is locked).

The example responses should be preceded by the request that generates the response. This might make the sequence of discovery, introspection, etc. easier to comprehend.

*The example interactions were removed in Rev 08*

In Section 5.6, the PUT response should be "HTTP/1.1 205 Reset Content".

[Dirk-Willem van Gulik] The discovery is a lovely addition. However from the spec it seems that a lot of the functionality is already in web DAV, and to some extend it feels like re-inventing the wheel within POST as to avoid existing verbs in HTTP, such as PUT, DELETE and DAVs versioning scheme. Also - some things may be better done 'out of band' - i.e. on HTTP header level, rather than overload the payload of HTTP itself with two types of 'data'. If the reasoning behind this is that _todays_ most popular webserver does not expose enough to PHP, CGI or Perl - then it may be easier to simply fix the web server to pass PUT/DEL, etc easier to cgi or the application langauge; openup DAV a bit more and make the headers more accessible.

[ mailto:rsalz@datapower.com Rich Salz] I think a more pure SOAP-based approach is better. I'm also concerned about how the API ties the entry to the content. I wrote about the current draft, and my proposal, in [WWW]a column for xml.com. I would be happy to flesh it out in more detail if there is interest. (Please send me email if so, since I can't always keep up here.)

There's far too much introspection going on here. You've got link tags, an RSD file, an introspection file, and an API. And none of these answer the really important introspection question for tool authors, which is: what elements are required, what elements are supported, and are other elements accepted (stored but not used). [AaronSw]

Fleshing out ProfileMatrix and converting it into camera ready copy would be greatly appreciated. [JoeGregorio]

RSD has been dropped from draft 7. Now using LINK tag in HTML that points directly to introspection file. [WWW]draft 7 section 5.1.1: introspection autodiscovery Discuss in AutoDiscovery