UserPreferences

RestEchoApiDiscuss


  1. Introduction
  2. Latest Versions
  3. Change Log
  4. Comments/Recommendations (Current Version)
    1. Emphasizing roles, de-emphasizing Atom format
    2. MIME type
    3. WSDL
    4. Spam
    5. Search
  5. Discussion
  6. Targeted Discussion

Introduction

The Atom API is a specification that leverages the Atom feed format in a content editing API.

Latest Versions

The latest version of the RFC can be found at: [WWW]http://bitworking.org/projects/atom/
A different shorter proposal is: [WWW]http://notabug.com/2002/awiki/api

Here is a [WWW]Quick Reference To The AtomAPI

Here is an [WWW]example of how the current API can be extended.

Change Log

Differences from version 7 to 8:

  1. Merged the Introspection file into the Atom feed formatted FeedURI.

  2. Dropped user preferences

  3. Merged the search facility into the FeedURI.

  4. Added section on which elements are required/optional/forbidden in different contexts.

More details of what was incorporated can be found on EchoApiChangeLog.

Comments/Recommendations (Current Version)

The meaning of the link tag in the 08 revision is dependent on the value of the 'rel' and the 'type' attributes. There is also the possibility of using the 'rev' attribute. The mapping of these values to their interpretation is done on LinkTagMeaning .

Emphasizing roles, de-emphasizing Atom format

[WWW]loosening the API -- proposed changes ([WWW]blog entry)

MIME type

[MURATA Makoto] I recommend the use of the charset parameter for application/x.atom+xml. E,g, Content-type: application/x.atom+xml; charset="us-ascii"

[JamesAylett] What benefit does this give? Do you need to know the charset/encoding before you start parsing the body of the XML (after the <?xml...?> bit which tells you explicitly)?

[AsbjornUlsberg] I say we recommend not put charset information on the HTTP load, because this will be difficult for people to change, and we will most definately get situations like;

...
Content-Type: application/x.atom+xml; charset=iso-8859-1

<?xml version="1.0" encoding="utf-8"?>
...

WSDL

[ChrisFerris] I've made some comments on the current draft WSDL in my[WWW]blog.

Spam

See CommentAuthentication.

Search

Moved to RestEchoSearchApi.

Discussion


Questions: How should authenication and security be handled? Are Basic and Digest good enough?

[EthanFremen] The application-layer digest is a great idea, but why confuse the notion by munging the header names? It's just a pure implementation of Digest Auth, but at the application layer. Let apps that already know how to do digest auth not have to re-learn how to do it just to talk to the Atom api.

[RickOlson] +1 for using Digest Authentication rather than remaking the wheel with Atom Authentication.


Question: How should errors be handled? That is, an HTTP Status code needs to be returned when an operation fails. Should there be a response body on errors, and if so, what should it look like? I see three possibities, if you have other ideas please add to this list:

  1. Don't specify a format for the response body, let the server decide the format of what to return.

  2. Specify a mimi-type of the text/plain, so the error string can be presented to the user.

  3. Return and XML file with formatted error info:

       <error> 
            <title>Can't create Entry</title>
            <description>Your bloggging service subscription has expired. 
                Visit reup.example.com to renew your subscription today!</description>
        </error>
    


Question: How should the state of an Entry be modified, where state can be (draft, published, syndicated).


[AnswerMe]: Are fully qualified URIs required, or can relative URIs be used instead, ala xml:base?



[SamRuby RefactorOk] Here's a list of suggestions, based on my experiences with SOAP. Feel free to adapt them to become more restful or to your tastes.


[ChrisWilper RefactorOk] I think there need to be a couple other methods to support editing of entries and comments. These should get the *source* of the entry (rather than the to-be-disseminated version), as this is what needs to be edited. Let me explain. A lot of blog servers do this thing where they accept tags and text that mean something special to the specific blog engine. One example is livejournal's "lj" tags. These have special meaning and are converted in the server on their way to consumption. Another example is the comments for this blog. Like Word, it converts asterisks to "b" or "em" tags before consumption. Then there's what wikis do with ThingsLikeThis. In each of these cases, what the editor submits is different than what is eventually disseminated. This pattern is prevalent enough that it's something that should probably be supported; otherwise the API will have limited usefulness. To support it, there should be a method in the API intended for editing that gets the source of the entry/comment (not the to-be-consumed version).


[MikeDierken] I really would like to be able to POST a list of entries in one request. Would that be suppored via sending content with a root of <entries> or something list-like?

[AsbjornUlsberg, RefactorOk] Can't we keep the current structure, and rather enable POSTing a full <feed> instead?

[MikeDierken] Sure - I'm not suggesting the XML format to be used, just that it support multiple entries.

[AsbjornUlsberg] Ok, then we're in the same boat. I agree with you; it should of course be possible to post several entries at the same time.


[AdriaanTijsseling RefactorOK] A list of comments on Draft #3. I'm basing my comments on my experience using the MovableType API and the variety of user wishes and requests I have received over the past year. The Draft is very nice and Joe Gregorio has done a good job setting up an initial API. Below are what I are missing and what I *know* will be demanded by users. Let me list my comments first and then thanks to the way of wiki some discussion may ensue.

    <categorylist> 
      <category>fluffy little things</category> 
      <category>blue skies</category > 
    </categorylist > 

There's no support for protecting against simultaneous edit clobbering. That is:

Alice GETs entry 1. Bob GETs entry 1. Bob POSTs his edited copy. Alice POSTs her edited copy and thus clobbers Bob's changes.

There needs to be a provision, if not an outright requirement, that Alice's POST is rejected with a warning. [AaronSw]

[DannyAyers] Is that in scope here? Say the application supported different levels of rights/privileges. Alice is the company boss - she can clobber who she likes.

[ZhangYining] Maybe what's needed is a Error/Exception structure like the SOAP Fault header, error handling leaves to each implementation and application built on top of it.

[JoeGregorio] This can be handled via the HTTP headers. For example, when you do a GET of the Entry for editing, it can return an ETag, when you POST the updated Entry you can include an If-Match header that containts the ETag. Now, that would make more sense if you PUT the Entry back to the same URI you got the Enrty from for editing.

[AsbjornUlsberg] I think HTTP headers don't give enough information. We could combine HTTP headers with additional body/content that explains about the error, but thorough explanations should be given. Many HTTP error codes are used for various errors, especially the 50x codes. I think we should define a set of Echo-specific error codes and a format which error information and explanation could be embedded in. The SOAPs Fault header is a good solution, imho.


Some examples on how to deal with server-supported convenience syntaxes would be good. (Which are supported should be declared through introspection, and then the server can send them using their media type and get back the convenience syntax and the generated HTML.) [AaronSw]


[JonathanPorter] It seems like Introspection are Preferences would be best served by OPTIONS verb.


[HenriSivonen] Instead of POSTing a new entry inside an envelope, how about [WWW]POSTing an XHTML document with possibly some extra metadata? The benefit is that the minimal case degenerates to just XHTML with no Atomness needed. (My premise is that the payload would be XHTML anyway, so the need to engineer for generality is questionable.)


[BayleShanks] I didn't understand how a client asks for a list of entries. Is a request sent to the "feed URI" meant to be interpreted as such a request? The spec just says "the FeedURI is used to retrieve a represenation in Atom format". Perhaps this should be explained more?


Targeted Discussion

If a thread gets long in RestEchoApiDiscuss it will be broken off into it's own topic page. For example:


CategoryApi, CategoryMetadata, CategoryRest, ProtocolDataModel