See also :
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:b="http://www.blogger.com/api#"> <soap:Header> <atom xmlns="http://purl.org/atom/ns#"> <b:blogid>1234567</b:blogid> <b:username>joeblogger</b:username> <b:password>s3cr3t</b:password> <b:appkey>0123456789ABCDEF</b:appkey> </atom> </soap:Header> <soap:Body> <feed xmlns="http://purl.org/atom/ns#"> <entry> <title type="text/plain" mode="escaped">Posting with the new API.</title> <content type="text/html" mode="xml">Hello, <em>new</em> world!</content> <issued>2004-01-01T01:00:42</issued> </entry> <entry> <title type="text/plain" mode="escaped">Posting a second entry with the new API.</title> <content type="text/html" mode="xml">Hey, you <strong>guys!</strong></content> <issued>2004-01-02T01:00:42</issued> </entry> </feed> </soap:Body> </soap:Envelope>
Authorization and blog id in the SOAP envelope.
Media types on both title and content.
Title is optional. Free Blogger blogs historically didn't have titles.
Post date (issued, in DublinCore terminology)
On success, method returns either the full well-formed entry, or post-id (or post-id+permalink -- TBD)
Multiple entries can be uploaded at once, to make posting via offline clients easier.
Please add them at the bottom of the page.
[AaronSw] I think using SOAP here is a mistake. Using HTTP Authentication (which is widely supported by tools) and putting the blogid in the URL seems like a much better system.
[MishaDynin, RefactorOk] Support for this option is not mutually exclusive with SOAP support.
[AaronSw] So then what's the benefit to SOAP support? (The cost is complexity in having to read SOAP specs and accept all the various forms of SOAP.)
[MishaDynin] You're are overestimating the complexity -- only document literal SOAP needs to be used, and that's basically an XML envelope over XML document. Benefits: short term -- wsdl.exe. Long term -- orthogonal extensibility. Now a question for REST: Blogger has separate options for posting, publishing the post, and sending the content of a post in an email. How do you represent that using HTTP/REST?
[AaronSw] Can you provide a wsdl.exe example? From what I understand orthogonal extensibility can be done using HTTP headers. As for your question, change the URL: POST /new, POST /firstname.lastname@example.org. I've not decided what the best way to publish is yet.
[JustinErenkrantz] HTTP does not directly allow for broad semantics such as 'send the content of a post in an email.' However, a handler/script could generate a form for a page/resource to do this. The target URI of this form would receive a POST body (or GET query args) for determining who to send an email to. So, it could be handled indirectly compared to a SOAP-centric customized RPC call. In REST/HTTP, I would imagine that posting and publishing the entry would be identical behaviors (if you are posting, why aren't you publishing it?). A staging resource could be used if you wanted to post, but not publish - most likely using some semantic like DeltaV's activity resources - see RFC 3253. This is how WebDAV-centric content management systems handle the distinction between posting and publishing. But, you don't necessarily want to do WebDAV for a blog.
[DiegoDoval] Looks good. I wonder if the specific mention of title, content and issued tags implies that the call would be limited to those elements only. I think as far as the spec goes the Body should contain a WellFormedEntry, and then each server would be able to define what can be used and what can't.
[MishaDynin, RefactorOk] The problem is that parts of well-formed entry (e.g. ID and Link) are assigned by the server, so the client cannot create a full WellFormedEntry. How do you propose dealing with this problem?
[JoeGregorio] Yes, we need a matrix that specifies the 'required-ness' of each element in an Echo feed based on it's context. Id and link are good examples of information that are required in an Echo feed but should not required in this context.
[JoeGregorio] I don't see a problem with the SOAP envelope, as that may enable higher level tools like VS.NET to use the API more easily. I would like to see it be optional though. In addition, I would like to hear your thoughts on 'blogid' and authentication, for example, one way to refactor your example would be to put the blogid into the URI that this Entry is being posted to. Similarly, the name and password can be done via standard HTTP authentication, either Basic or Digest.
[MishaDynin RefactorOk] SOAP envelope can be made optional for a simple post. However, there might be issues for other methods. Even with post -- Blogger has a concept of "publishing", that is independent of posting. Where do you specify whether a post should be published or not for no-envelope approach?
[JoeGregorio] Does their need to be a new element in Entry that specifies whether or not it is published?
[MishaDynin RefactorOk] They are not really part of the entry, but are a separate object -- called "actions" in the API 2.0 draft. The "draft" flag can be made part of an entity; whether the post should be published or syndicated (emailed), imho, should be part of the envelope since that's only relevant to the post creation transaction.
[TimothyAppnel] +1 For SOAP AND HTTP/REST support.
[DiegoDoval] How about just SOAP or REST? I'm concerned that if we specify two protocols, weblog developers will implement one or the other, not both, and so interoperability will be effectively lost.
[DannyAyers] I'd go for both REST and SOAP normative references, 'Necho API Compatibility' means you support one or both of them. I doubt whether this will cause major interop problems because it won't be much harder to implement both than one - most (sensible) vendors will do both.
[AsbjornUlsberg] Extending the REST interface to a SOAP interface should be rather straight-forward, so I say "aye" to both SOAP and REST.
[MishaDynin RefactorOk] Blogger (at this time) will silently ignore categorization information. There will also be a DiscoveryProtocol that will allow a client to find out what features are supported, to be discussed later.
[DaveWarnock RefactorOk] If a "DocumentLiteral" approach were taken to soap (which according the links is the preferred direction for the future), then would the differences between a SOAP and a REST server implementation pretty much disappear for the client? If I am correct then my concrete suggestions are
Support HTTP(S) POST with HTTP Authentication of an Entry as XML in the EchoExample format. If <link> and <id> is not provided then this is a new entry, otherwise it is an edit. For new entry's the rules for what is required are as EchoExample, for an edit only <link> and <id> are required (allowing the option to send only changes, could have significant performance benefits if content is large and you are only changing a category or title etc).
I can't make up my mind whether the POST should return the full wellformed entry (which is nice because you see what the readers will see - maybe the server adds standard extra stuff), or just the link and id which means you get an entry that does not meet the spec for entry (but you get it much faster due to size). Maybe we need a new xml enlement of entryid with just link and id in it.
How would delete work using SOAP?
[MishaDynin RefactorOk] This is an example of how a post request might look like -- as indicated above, it's possible that both SOAP and HTTP/REST approach (with HTTP authentication) will be supported. In case of SOAP, extra information (such as request type -- newpost, deletepost, etc.) can be added to the SOAP header.
[DaveWarnock] Misha, I meant more like this.
POST /news/0101679 HTTP/1.1 Authorization: Basic gObBlEdYgOoK <?xml version="1.0" encoding="UTF-8"?> <entry> <title type="text/plain" mode="escaped">Posting with the new API.</title> <content type="text/html" mode="xml"">Hello, <em>new</em> world!</content> <issued>2004-01-01T01:00:42</issued> </entry>
Will that work with a SOAP server working in DocumentLiteral mode? If so we have a very neat match between the feed and the edit api. Not only that but the server writer can choose to use SOAP or not.
[MishaDynin RefactorOk] You give a perfect example of what a REST binding can look like. AFAIK, SOAP requires an envelope, so this will not work with a SOAP server; but the Echo bindings are not finalized -- we may end up supporting both SOAP and REST. More discussion is on Sam's blog.
[DaveWarnock RefactorOk] Yep, I know it looks like REST, and like Tim's suggestion for a Web API. BUT I struggled through the page at Microsoft that DocumentLiteral points to and it seemed to me from that that this is valid for SOAP in DocumentLiteral mode. I know that REST advocates had made some "progress" with the latest specs and so hoped that we could find an on the wire form that both could use. I say that as I am quite negative about making SOAP the default API.
[DareObasanjo] It isn't valid SOAP. There's no envelope.
[KenMacLeod] Correct, it's not valid SOAP. I think the functionality people might be thinking of is "can my toolkit use either SOAP or XML over HTTP" and the answer to that questions should be "yes" using WSDL. The answer may not be "yes, right now" but it is an argument for holding off on a required SOAP envelope in favor of alternative solutions that will also work today.
[AsbjornUlsberg] Therefore, we sketch out the REST version first, and do a SOAP one afterwards. It's smart to wait with everything regarding SOAP until v1.2 is fully embraced and implemented, as v1.2 is the first real SOAP-standard from W3C. 1.0 is just an assembly of ideas, 1.1 is a hack, but 1.2 has gone through thorough revisions, discussions and tests before published.
[BillSeitz] Does Blogger intend to start offering feeds to non-Pro users? That seems more important to the ecosystem than the flavor of feed. (I'm pretty sure it's the main reason that BlogDex and DayPop don't even use RSS, but scrape front pages instead.)
if no, then what about improving the "containerization" on each blog's front page, like by putting "a name" tags around each entry?
[MishaDynin] Bill, offering feeds for non-Pro users is being discussed. Currently there are some technical and some non-technical problems with that. As for "containerization" -- Blogger users can create custom templates, and we don't control that.
[RahulDave] Must Each post have username and password in the header? What about using a cookie in the http header (non restian i know) or even in the soap header? Perhaps the cookie can be used in place of the password once the authentication is done. Blogger proper dosent require reuse of password again, just the 'remember me' cookie...
[MishaDynin] Security is a separate topic -- using Blogger cookie is one possibility, although it wouldn't be portable to other services. Another thing to keep in mind is that the requests can be sent via HTTPS.
[GuilleBe] Is this missing an appkey?
[MishaDynin] Yes it is. It is also missing a "publish" action specifier. Both can go into the SOAP header.
ChrisJohnson: Like Aaron and Dave Warnock, I continue to be opposed to using SOAP as the default API. I suppose at this point in the discussion, and without an important URL attached to my name, my remarks will be ignored or just deleted. But as someone who has been programming RPCs and distributed computing since the 1980s, using everything from naked socket level programming to DCE to XML-RPC to SOAP, I feel I've got the experience to say that SOAP is gross overkill for this application. It's far too complicated, and the number of arguments about various technical aspects of it above on this page is supporting evidence for that statement. I used SOAP for a couple of different projects, and both interfaces were eventually discarded for simpler methods. In one case, going to XML-RPC made life much easier and still provided every necessary and nice-to-have feature, without the fragile, inefficiences of SOAP. Sorry about dumping a screed here, but I strongly believe that using SOAP will be a detriment to success in the long run. Regardless, whatever you all come up with I'll end up implementing in Drupal http://www.drupal.org. Ok, let's use REST then...