- Introduction
- Latest Versions
- Change Log
- Comments/Recommendations (Current Version)
- Discussion
- 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: http://bitworking.org/projects/atom/
A different shorter proposal is: http://notabug.com/2002/awiki/api
Here is a Quick Reference To The AtomAPI
Here is an example of how the current API can be extended.
Change Log
Differences from version 7 to 8:
-
Merged the Introspection file into the Atom feed formatted FeedURI.
-
Dropped user preferences
-
Merged the search facility into the FeedURI.
-
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
loosening the API -- proposed changes (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 myblog.
Spam
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:
-
Don't specify a format for the response body, let the server decide the format of what to return.
-
Specify a mimi-type of the text/plain, so the error string can be presented to the user.
-
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).
-
Answer: At this time, the state of an entry would be a tool-specific extension as there appears to be no common technique across existing tools -- a common technique should emerge first before attempting to standardize. There used to be an Authoring extension that targetted tool-specific metadata, including tool-specific entry syntax; that part got lost when it was factored into BiblioGraphy. CMS folks also tend to use WorkFlow to handle state, there appear to be several promising WorkFlow technologies that aren't wikied here yet.
Answer: A 'tool:state' property would go in the entry, and one would use PUT to update the entry.
-
Question: Is the "tool" prefix really necessary? Wouldn't developers have to add an additional namespace to handle it? [LewisMoten]
[AnswerMe]: Are fully qualified URIs required, or can relative URIs be used instead, ala xml:base?
-
[AsbjornUlsberg] What URIs are you thinking of, exactly? Inside the Echo format, relative URIs can be used. At the HTTP level, we follow the usual standard, don't we?
[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.
-
Define the error paths, in particular, the case when the server is unable to interpret or comply with the request. Clearly this should involve things like HTTP status code 500, but ideally there would be more. In SOAP, for example, there is are additional faultcode, faultstring, and detail defined. These can be used to provide things like stack tracebacks which are invaluable in debugging why a given server implementation doesn't interoperate with a given client.
-
Rigorously define the format of an entry with the schema language of your choice. Popular choices are RelaxNG and XML Schema
-
Something to consider: if optional soap envelopes and bodies are permitted, and a schema is defined, then a WSDL could be produced. This minimal investment could significantly increase the number of toolkits that can participate.
-
[JoeGregorio] A quick reading of the WSDL Specification indicates that it does not require soap envelopes. To quote the specification, "WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME." Further on in the specification it allows all the HTTP verbs, "he value of the required verb attribute indicates the HTTP verb. Common values are GET or POST, but others may be used. Note that HTTP verbs are case sensitive." [4.4 http:binding http://www.w3.org/TR/wsdl#_http:binding]
[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).
-
[JoeGregorio] Doing a GET via the AtomAPI always gets you the source and does not get the processed content. A clarifying note needs to be added to the draft RFC.
-
[AsbjornUlsberg] If we decide to allow aggregators to add an URL to their alternative of the entry to the entry itself, this should be reflected in the API. Also, the URL to retrieve the original entry is the original <link>-element which should follow the entry wherever it goes.
[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.
-
In "Creating a new Entry request", a link is returned, which has then to be queried to get an id of the post (for example). Why not return <link/>, <id/>, <created/>' and <modified/> right away? Most weblog APIs only return the id of the post. Returning link, id, and created on entry creation would be best. The date modified tag would only be used when an existing entry is edited (which would be in "Editing an entry".
-
The entry creation, editing, and retrieval needs values for categories. Categories are a prominent feature in most weblog systems (MovableType, Nucleus, and so forth). There is no category support in this draft at all. One could add a field
<categorylist> <category>fluffy little things</category> <category>blue skies</category > </categorylist >
-
additional fields (maybe this should go in a different wiki page) may be "keywords", plus a set of values indicating whether this new entry permits users to comment on it, leave trackback pings to, and whether the weblog system should parse the content and add linebreaks. Also, a field containing URIs to send trackback pings to should be added (note that I am modelling after the MovableType API, which is by far the most complete of all).
-
I miss the get category list, which would be a simple call returning an array of categories. In addition, some weblog systems (i.e. MovableType) allow for special text formatting rules to be applied to a entry's content. Clients have to know what formats are available. As such, something similar to MovableType's mt.supportedTextFilters should be supported.
-
[KenMacLeod] Re. categories and additional fields: yes, they should go on a different wiki pages, as they are part of the ConceptualModel, not the API. Categorization for categories. The additional fields as you describe them sound like directives to the publishing tool (which used to be in a module called Authoring but now seems to have been lost in a move to BiblioGraphy).
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 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:
-
CarrotVsOrange -- discusses the alternative to REST, "HTTP using GET/POST to a single URI".
CategoryApi, CategoryMetadata, CategoryRest, ProtocolDataModel