API Change Log
Differences from version 6 to 7:
-
Removed the use of the RSD file for auto-discovery.
-
Changed copyright until a final standards body is chosen.
-
Changed query parameters for the search facet to all begin with atom- to avoid name collisions.
-
Updated all the Entries to follow the 0.2 version.
-
Changed the format of the search results and template file to a pure element based syntax.
Differences from version 5 to 6:
-
Added template editing interface.
-
Moved to PUT for updating Entries.
-
Changed all the mime-types to application/x.atom+xml.
-
Changed 'edit-entry' to 'create-entry' in the Introspection file to more accurately reflect it's purpose.
Differences from version 4 to 5:
-
Renamed everything Echo to Atom.
-
Added version numbers in the Revision history.
-
Changed all the mime-types to application/atom+xml.
Differences from version 3 to 4:
-
Updated the RSD version from 0.7 to 1.0.
-
Change the method of deleting an Entry from POSTing <delete/> to using the HTTP DELETE verb.
-
Changed the query interface to GET instead of POST.
-
Moved Introspection Discovery to be up under Introspection.
-
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.
-
[JoeGregorio] Added in version 02.
[TimBray RefactorOk] (section 4.4) text/xml is evil, blecch, don't use it. Use app/not-echo+xml throughout please.
-
[JoeGregorio] Even for pieces of XML that aren't entries, like <delete id="urn:example.org:reilly:1" /> ?
-
[TimBray] Yep, if it's XML just use application/xml. But why shouldn't <delete> be a NotEcho element?
-
[JoeGregorio] Added in version 02.
[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?
-
application/not-echo+xml: Create New Entry, Edit an Entry
-
text/xml: Deleting an entry, Editing User Prefs, Set User Prefs, Adding Comments
Are the text/xml methods not specified by Echo?
-
[JoeGregorio] Fixed in version 02, all content types are now application/not-echo+xml.
[AaronSw] Querying for entries is sorely missing.
-
[JoeGregorio] Added in version 02.
[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).
-
[JoeGregorio] Added in version 02.
[TimBray] General comment: URI not URL throughout. URL no longer has a normative reference and stands only for Universal Republic of Love.
-
[JoeGregorio] Added in version 02.
[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.)
-
[JoeGregorio] Added in version 02.
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]
-
[JoeGregorio] Added in version 03.
[AaronSw] Discovery should go first, since that'll be the first thing a client app does.
-
[JoeGregorio] Added in version 03.
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?
-
[JoeGregorio] Fixed in draft 06.
[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?
-
[JoeGregorio] Fixed in draft 06.
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:
-
GET to retrieve a resource or perform a read-only query
-
PUT to update a known resource or to create a named resource
-
POST to create a new dynamically-named resource or perform an update-query
-
DELETE to remove a resource
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.
-
[JoeGregorio] A version of this was added in draft 06.
Question: Should templates be handled by this interface?
-
Answer: Yes, templates should be handled by the PieApi (particularly as they are already supported in the Blogger and MetaWeblog APIs).
Question: How are templates handled?
-
Answer: Generally like most other resources in a REST interface, with PUT and GET. The interface document can answer questions like: what is the base URI for templates (introspection)? are there common templates across tools, can we share names? can the publishing tool support creating new templates on-the-fly or only predefined templates? The interface document should not try to answer, but at least make clear, that different publishing tools use different placeholders and templating syntax within their templates.
-
[JoeGregorio] Templates added to draft-06
[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) .
-
[JoeGregorio] A note had been added in the 06 draft that the headers shown are not complete.
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>
-
[JoeGregorio] Added in draft 07.
[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
-
[JoeGregorio] Added in draft 07.
[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).
-
[JoeGregorio] Fixed in draft 07.
[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.
-
[JoeGregorio] Changed in draft 07, though still under discussion.
[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?
-
License has to do with the entries and feeds created by Atom publishers, it is in no way connected to ProjectLegal. ProjectLegal has to do with the specifications, organization, and process we're using here on the wiki to develop the Atom formats and interfaces, and have no effect on how publishers choose to License their entries, feeds, or other resources (except to say how they should communicate that information in Atom formats).
-
[JoeGregorio] Fixed in draft 07, but changing the copyright to myself, until a standard group is chosen.
ProjectLegal is where final consensus should be reached on legal aspects of the Atom project effort. With that in mind, it is common for Internet Drafts (if one is proposing that avenue be used) to have an ISOC copyright and license. More likely though, the rfc2xml tool Joe is using supplies those sections automatically by default and Joe has not chosen to disable that or put in AtomProject dummy notices.
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.
-
[JoeGregorio] PostURI is used for both creating new entries, new comments and new trackbacks
-
depending on the context.
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 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).
-
[JoeGregorio] This needs to be fleshed out in ProfileMatrix, which is a need not just for the API but for the Atom format.
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
-
[JoeGregorio] Nick, the URLs are not canonical or constructed. The actual form of the URL is up to the CMS. The URI for prefs just as easily have been http://example.org/reilly/cms.cgi?interface=prefs
-
[NickChalko RefactorOk] Then why is it listed in the RFC? How will a tool know what URI to set user preferences?
-
[DaveWarnock RefactorOk] There URI is discovered using the Introspection File described in 4 The EchoAPI Model. Obviously you need to be able to find the introspection file so see 4.6 Introspection Discovery (but it is not yet written ;-).
[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.
-
[JoeGregorio] Some weblogs do not offer commenting systems, and so the author outsources the comment service to a third party.
[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...
-
[JoeGregorio] The API does not specify the form of the URLs, but instead documents the formats and the actions that can be performed on the URIs.
[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>
-
[JoeGregorio] We can go with either RSD or the Introspection file. This just looks like a reformulation of RSD.
-
[Arien, RefactorOk] How about using HTTP's ContentNegotiation?
-
[JustinErenkrantz RefactorOk] Sure, passing Accept headers in the HTTP request could work as well. I've found being more explicit in the 'literal' resource about the representation is generally a better overall thing, but ContentNegotiation is indeed a bit more RESTy.
-
[BrentRockwood, RefactorOk] ContentNegotiation is clearly the way to go here, in my opinion. It's designed to handle this exact problem, and a solid standard already exists. Apache apparently has pretty good support for this. IIS support appears sketchy. Even with that hurdle, I think this is important enough to do anyway. It won't be easy to change once a few client implementations get going.
-
[JoeGregorio] I have had experience with ContentNegotiation and would like to avoid it.
-
Would you offer some details about your experience? There is a workaround for Explorer's use of only "*/*" which involves tweaking the ContentNegotiation "qs" value s on the server.
[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.
-
[JoeGregorio] I have read the WebDAV specification and from my reading it looked like there was a substantial difference in the amount of functionality WebDAV offers over the EchoAPI. I would be interested in hearing how closely the two were aligned.
-
[Dirk-Willem van Gulik] Both have a basic set of verbs on a set of objects, where each is annotated with a chunk of 'metadata'. Having said that - WebDav is ABSOLUTELY not a replacement; it is just that it may be a larger stepping stone than HTTP for echo to stand on. For it to work it would need a set of concepts/rules or well-known anchor points to be defined. However, the total amount of work would be far smaller than when you start with just HTTP. Although I am a known sour septic when it comes to DAV, when I look at examples like subversion.tigris.org, which have a protocol option that run over DAV, then I grudgingly have to admit that it does seem to have absolutely right at least the basic atoms of any publishing/content management interface. It can cope with versioning and metadata about the content well enough.
-
[JoeGregorio] "some things may be better done 'out of band'" Are you talking about using custom headers? Is there someplace in particular you see this could be used?
-
[Dirk-Willem van Gulik] What I mean is that HTTP itself already has verbs and headers outside the MIME-encapsulated payload. Echo does not make that much use of such; but instead has its own content inside the mime payload inside the content payload of HTTP, hence the need to start escaping, etc. Or, in other words, Echo could be run over just about any other protocol, as long as it has a few very basic 'REST-ish' verbs. Which seems a shame, as it probably is only going to run over HTTP. This also seems a shame because Echo thus falls into the same trap as SOAP does - where the lowest common demoninator of the features of the transport layer force reinvention of features inside the application protocol, even for those cases where the transport protocol actually has those features; just to 'make SOAP not protocol bound'. So, maybe, it would be possible to separate on MIME level: for example, using multipart-mixed and for example separate metadata as well formed XML in one blob and the <content>..</content> blob in another; or even furter -extend the HTTP headers -or- use the PROPFIND http level separation to convey some of that data.
-
[JoeGregorio] The idea of further extending the HTTP headers, as a place to store some of the desired information is a very important point that needs to be kept in mind as the AtomAPI evolves.
-
Moved here because it refers to an outdated version of the spec *
[ 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 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.)
-
Moved here because it refers to an outdated version of the spec *
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. draft 7 section 5.1.1: introspection autodiscovery Discuss in AutoDiscovery
-
Moved here because it refers to an outdated version of the spec *