UserPreferences

EditingApiArchive


At first guess I think there are at least three sides to look at :

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 :

[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)

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.

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.

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,

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?

API

This is a description of an API for client applications interacting with a server to publish a well formed entry.

See also:

[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] [WWW]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.

Abstract

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.

Notational Conventions

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 [WWW]RFC-2119 .

Entry Operations

post-entry

get-entries

[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.

[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.

[DareObasanjo] Depending on the kind of weblog none of the suggested operations map to retrieving the syndication feed file. Examples include [WWW]Slashdot and [WWW]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.

update-entry

[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 [WWW]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.

delete-entry

User Management Operations

get-user-info

set-user-info

Blog Comment Operations

post-response

[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] [WWW]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.