At first guess I think there are at least three sides to look at :
1. protocol angle
2. programmatic angle
3. serialization syntax angle
1. would cover the means by which a logging client communicates with the server
2. would cover the regular API definition stuff - abstract definition + bindings to selected languages.
3. would cover the relationship with other parts of this project, in particular how the syntax can be used as a messaging format, so that ratherr than saying "this is an entry" it would say "create this entry".
OpenQuestion Do the programmatic interfaces need to be exposed in any form other than XML? (i.e. can 2. and 3. be rolled together?)
Working out the implementation details usually comes after abstract modelling, but following the style elsewhere in the project, here are some random thoughts :
Syntax should be chosen so that method naming across language bindings can be kept consistent
The API must be addressable using SOAP parcels and minimal (RESTful) POSTs
XML-RPC may be supported (because of i18n issues this is probably best deprecated)
[AdriaanTijsseling RefactorOk] Since several XML-RPC implementations (e.g. MovableType) do allow for UTF-8 encoded content, it may be better to have XML-RPC support. (at least for backwards compatibility and/or the miracle event that the XML-RPC spec is modified to allow UTF-8)
-1 [TimothyAppnel] The stated goals of this initative is to create a common syntax for syndication, archiving and a publishing API. SOAP (Document Literal encoding) and HTTP/REST would permit this type of common syntax reuse while XML-RPC would be a kludge at best.
I don't think backwards compatibility should be considered a priority. First let's find out what's needed, figure how it should be done with an open mind, and only then consider legacy support.
[CarlGarland] As far as the Editing API goes remember there are 2 parts to the equation.
The server that must service the request
The tool that must communicate this request to the server
Currently both the Blogger API and the MetaWeblog API both use XML-RPC. Now converting the output of entries from RSS X.X to a new format is trivial compared to the work on servicing requests. I understand the possible benefits of Echo though so welcome the potential. Now though you tell me in addition to reworking the ability for the new function set I will have to ripout the underlying communication protocol and replace it with something that will take me longer and add much overhead because I must also support the old.
Toolmakers as well will have to add an extra layer.
Thanks for trying to add countless hours of programming for me and other developers and all for why again? I want Echo but I may not be able to support the Editing API if it only uses SOAP for many months until I get the time.
Is "RESTful POSTs" shorthand for all RESTful verbs? GET/POST/PUT/DELETE etc?
[PhilWolff, RefactorOk] Should there be blog lifecycle capability built into the API? For example,
Create a new weblog
Freeze, retire, suspend a weblog
Merge weblogs x, y, and z
Delete a weblog
Copy or move an entire weblog from this server to that server
Create a new weblog by extracting some content from weblog x
This would enable programmatic control over a weblog by an authorized system or person. For instance, you may want your HR system to automatically generate a weblog for each new employee, and freeze it when the employee leaves the company. Or to manage multiple blog servers (made by different vendors) using one admin tool.
[StevenGarrity, RefactorOk] - Is there some better alternative to sending passwords in clear text?
This is a description of an API for client applications interacting with a server to publish a well formed entry.
[TimothyAppnel] I propose this discussion focus solely on entry publishing and management to keep it focused. User management and comments publishing should be considered out of scope and to be addressed at a later date.
[DareObasanjo] I propose this discussion focus on the entirety of the API instead of working on various aspects of it isolation. This often leads to asymettry in functionality and interface. Secondly, the current state of the art in blog posting API already perform certain user management functionality which means to at least be attractive to adopters the API should provide some (if not all) of this functionality.
[TimothyAppnel] The low hanging fruit and the majority discussion of this wiki has been focused on the post and not bite off more then can be chewed. These "state-of-the-art" APIs do have such things, but they are quite tool specific. MT does not implement the blogger template functions because they are not compatable. MT implements category management functions that Blogger has no use for since it does not support categories. Blogger also doesn't support comments. TrackBack and the Comment API seriously overlap which needs to be rectified. These are very big issues tjat I think need to be considered out of scope for the time being. My reconmendation still stands that we should do one thing well (posts) and the rest will come later. I think it is likely the rest will come in the form of extensions (like the syntax using namespaves) that conform to certain specified guidelines.
For a conceptual model this page have gotten very implementation specific (HTTP methods, function calls, inferences to specific Web services protocols.)
I think the use of the word weblog here is a limiting mindset we need to break out of.
[AdriaanTijsseling, RefactorOk] One note of caution: It's all great and well to define a API conceptual model, but an actual implementation and usage of the API (i.e. putting it to test), will properly reveal what routines are missing, incomplete and/or what parameters and attributes needs to be added.
[GrantCarpenter, RefactorOk] Blogger v2 (DANO) API specs
[SeanConner, RefactorOk] I linked to several of the current APIs on my blog at http://boston.conman.org/2003/05/29.1 . In that same post, I discuss what I felt was needed for a blogging API. One of the things I did was separate out the various types of things an API could manipulate. I have a section for managing blogs themselves (creation, adding users, who can do what), managing users, catagories, templates and posts. I also tried to make the methods for each section consistent (the template, catagory, user and posts API as an edit method, info method and delete method for instance). I've been wanting some feedback, and maybe now, I can get some.
The Echo API describes a number of services a server can perform on the behalf of a client. The client sends requests containing XML or HTTP encoded messages and receives results as XML messages or standard HTTP message. This page is for the conceptual model of such an API. Discussion of the various types of web services and how to layer this model on those services is out of scope. See ApiProtocols.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 .
Description: Posts an entry.
[AdriaanTijsseling, RefactorOk] Actually, it should return the post id.
HTTP method: POST
Parameters: An well formed entry. (Needs to be more explicit.)
Returns: The post Id
Description: Retrieves a specific entry.
Other useful views are last-10, and all, last-10 being the last ten entries, all returning a list of all the entries ever made. How to incorporate into the above query parameters?
HTTP method: GET
Parameters: A search parameter. The following search parameters must be supported
[TimothyAppnel AnswerMe] This suggests that title will be required. It also precludes searches by last 15 entries (by date) or last X days. Should parameters be defined by the specification? Should there by different types of explicit GET functions?
[AdriaanTijsseling, RefactorOk] I'm missing one more variant to just retrieve the last X entries. I don't see whay it has to be limited to 10 or 15. Just one parameter to identify the number of entries desired and that's that.
[DareObasanjo] When I specced this I meant that there would be at least three versions of get-entries()
although looking at it now it probably wouldn't be a bad idea to have a
to get all entries within a particular date range.
[TimothyAppnel] These look like RPC calls. If they are I have to disagree with that assumption. I am of the mind that this API will be most effective if it is implemented in a document literal fashion.
[DareObasanjo] Please speak English, some of us are not XML Web Services gurus. What does "DocumentLiteral fashion" mean? I expect the queries to look something like the following http://www.example.com/blog/get-entries?startdate=1999&endate=2001 . I have no idea what XML Web Services buzzword these satisfy.
Returns: An XML document containing zero or more entry elements.
Authentication Required: No
[TimothyAppnel] How does this related to the retreival of a syndication feed file over HTTP? There seems to be a lot of commonality and overlap. Need to be clarified or consolidated.
[DiegoDoval, RefactorOk] There is a big difference. The programmatic "get-entries" returns information that obtaining the feed doesn't. The feed is public information, get-entries returns private information. In MovableType, for example, when obtaining entries through the programmatic API you obtain (to quote MT's document): struct containing String userid, ISO.8601 dateCreated, String postid, String description, String title, String link, String permaLink, String mt_excerpt, String mt_text_more, int mt_allow_comments, int mt_allow_pings, String mt_convert_breaks, String mt_keywords. That is, you obtain the internal structure of the post and its related modifiers. I think this is good enough reason to keep this method call.
[DareObasanjo] Depending on the kind of weblog none of the suggested operations map to retrieving the syndication feed file. Examples include Slashdot and Weblogs @ ASP.NET
[TimothyAppnel] In the view of RESTful architecture how is a GET on a syndication feed file any different the a GET post in the API. The answer: there is none. This aboslutely should map to the syndication feed file. Are you suggesting that REST not be employed?
[DareObasanjo] I mean that if you go to http://slashdot.org/slashdot.rss or http://weblogs.asp.net/MainFeed.aspx it isn't clear that GETing the information provided by either of the aforementioned feed files maps to any combination of the queries described above.
[JoeGregorio] RestLog actually breaks this up into two steps, the first step is retrieving a list of entries that can be edite, that list being in RestLogArchiveFormat, then once the user selects the file to be edited, that Entry is retrived by HTTP GET. RestLogArchiveFormat also gives an alternative to query parameters, by letting the server specify a navigation structure.
[ChrisWilper] Question: If current tools do this (with a range parameter), how do they deal with the case where there are thousands of results?
[ZhangYining] Is this confusing between searching entries that match a set of criteria and getting a specific entry (probably optionally with comments and trackback) with a given post id? I propose we have separate method for each.
Description: Updates an entry.
HTTP method: PUT
Parameters: An entry which must contain a means of identifying the entry that is being updated.
Returns: Success or Failure.
Authentication Required: Yes
[SeanConner] Question: What is the difference between post-entry and update-entry? Both are conceptually modifying an entry.
[DareObasanjo] post-entry doesn't need to know its URI ahead of time while update-entry does.
[SeanConner] Okay, I can see that. My original thoughts were to make the URI of the post optional and if not given, then it's essentially a new post. I can live with this though.
Description: Deletes a blog entry.
HTTP method: DELETE
Parameters: An identifier for the entry being deleted.
Returns: Success or Failure.
Authentication Required: Yes
User Management Operations
Description: Retrieves information about a specific user.
user's contact email (if owner of the blog)
user id (string or number uniquely identifying the user) [AdriaanTijsseling]
HTTP method: GET
Parameters: A user identifier such as a username or email address
Returns: An XML document containing information about the user. The contents of this message will vary depending on the weblog server but the following information must be present
Description: Sets information about a specific user.
user identifier such as user name or email address
user contact email
HTTP method: POST
Parameters: An XML document containing information about the user. The contents of this message will vary depending on the weblog server but the following information must be present
Authentication Required: Yes
Blog Comment Operations
Description: Posts a response to an entry on a weblog hosted by the weblog server.
HTTP method: POST
Parameters: A Pie entry and a way to specify the entry being responded to.
Returns: Success or Failure
Authentication Required: Optional, weblog servers may choose to authenticate users before allowing them to post.
[SeanConner] Question: What's the difference between a comment and an entry, other than the author may be anonymous? If you allow for a post to have a parent-post, then when posting when parent is not specified makes it a post, but otherwise it becomes a comment under the parent-post (and this extends to having threaded discussions).
[DareObasanjo] You're right. A comment is just an entry that has some sort of ID and may require less authentication to post.
[JoshJacobs RefactorOK] Given that different blogs have different 'soft-policies' regarding anonymous comments, blog address of poster, etc, does it make sense to have a seperate API call to get retrieve an XML based comments policy? A policy would allow posting tools to enforce required fields in the comment post, and give users direct feedback, rather than either forcing all blogs to accept any new comment request, or just having servers rejecting comments with no useful feedback.
[DareObasanjo] This sounds very out-of-scope. Defining a general format for describing weblog posting/commenting policies is a significant task and IMHO more difficult than figuring out the syndication format or a blog posting API.
[JoshJacobs RefactorOK] Dare, it sounds like the API's you would like to see supported are focused on blog authors, but not on blog readers. I'm trying to figure out if this category is totally out of scope, a seperate effort, etc. See also my post about authenticated feeds. I don't want to assume your thoughts, would you mind making a specific statement about API support for aggregators specifically?
[StevenGarrity RefactorOK] These are great ideas - I would love to see a commenting API with support for varying levels of required fields. However, I'd rather see this moved to a Pie/Echo v1.1 (or somewhere post 1.0) to avoid bogging down the basics. The sooner we can get systems supporting the basics, the more traction we'll get (giving us a greater platform for future improvements, like a commenting API).
[DareObasanjo] The fact of the matter is that you want adoption. Creating all sorts of new features that aren't even supported by the common underlying engines is a lot of work. For instance, for the feature you describe above trying to distill the various technical (what is the allowed HTML) and social (what is the copyright policy on comments) issues involved in accepting posts from users into some XML format is not a trivial effort. And that's just one API call. What I'd like to see is a common API that exposes the currently supported features of the more common weblog engines as opposed to brainstorming fantastic new stuff then expecting various vendors to implement them without hesitation. By the way, what post about authenticated feeds are you talking about?
[JoshJacobs RefactorOK] Dare, the post is on a new page called ReaderAPI. I totally agree on simple supporting weblog engine adoption. I'm arguing in favor of enabling new capabilities in aggregators, and looking to determine whether anything is this area is even in scope for this effort (now, or in the future under the echo umbrella). For what it's worth, I could see comment policy starting out pretty simple: Most common comment forms have name, email, and weblog fields that go along with the content. Some blogs seem to require all, or at least some, of these fields in order to post comments. That's current functionality, but there is no way for an external tool to determine this and express the required nature of the fields to the user.
On the policy feature, I could easily see this as a namespaced extension that bloggers could support if policy was important to them, and aggregators could then make the decision whether to support the extension (and the resulting better user experience) or ignore it. The key thing is that if this is a use case that we want to support, then the commentPolicyModule needs to be defined and blessed under the auspices of the spec. It seems like there are 3 categories which will end up existing: 1) Core Spec, 2) Official Modules, 3) Vertical Modules. I see official modules getting decent support (not as great as core) but certainly better then current modules that exist on a standalone basis.
I understand the focus on blogging tools, but I feel like aggregators are getting short shrift in the discussions, and I'm trying to figure out whether we should defer these conversations, drop them, work them in parallel, etc. Maybe the best thing to do would be to start a seperate page on the key modules which should be speced as part of 1.0?
[JoshJacobs RefactorOK] Scoble writes about klip. He makes some predictions about innovation at the end that I totally agree with:
But, it predicts some more trends. 1. That innovation in the future will happen in Smart Client apps. 2. That end users care about user interface more than just raw great content. 3. That if you make something easy to install, easy to discover, and more productive, you can change the rules.
I couldn't agree more with point 1, and the audience for point 2 is larger by far than bloggers writing. I really want to see API's that make it possible for killer end user applications, and I pay for software!
* IsaCommentAnEntry concluded that a comment is an entry.
[AsbjornUlsberg] As comment is an entry, I don't see any reason for having different functions for the both. It's only the authentication and required data that differs, and what data is requires is up to the aggregator to decide. The aggregator can i.e. decide to handle both comments and entries the same way, demaning the same authentication level, the same data, etc. from both.
If we only have one function for this, it will be easier to extend (we don't have to extend both functions as the data model expands), it will be easier to define methods for threading (as all entries and comments conceptually and in practice are the same), it will be easier to implement in aggregators, etc.