First sketch

This is a collection of some initial ideas for a new Weblog API meant to replace the Blogger API. The Blogger API was designed to specifically meet the needs of the original Blogger service. Because of this, it has some major limitations which this proposal tries to overcome. Some of the ideas covered here come from Dave Winer's MetaWeblog API and the discussion that followed it, and this posting by Evan Williams. I've added some of my own ideas on top of that.

The main purpose of the API described here is to enable remote content editing. The functional scope is similar to that of the current Blogger API, but (at least for now) I'm leaving away non-content related stuff like template management.

I'm writing this with XML-RPC in mind and make heavy use of XML-RPC terminology, but there should be no reason why it couldn't be implemented with SOAP or some other protocol.

This first sketch also leaves out all the important details. The purpose is to describe the basic framework of the API.

Basic Design Principles

Maybe the most important design idea in this proposal is the use of structs for some central types of parameters. The main advantage compared to fixed parameter lists is that it allows for an interface that is concise and clear and at the same time extensible and able to evolve. Clients and servers can and should ignore the struct members they don't understand. This allows us to accomodate applications with sightly different feature sets, and it also gives us a way to evolve the API over time in a compatible manner by adding new struct members if needed.

It is also possible that individual applications choose to extend specific struct types by adding members not defined in the spec. For this, I propose a scheme similar to that used in the MIME format in that non-standard struct members must have a name starting with "x-", e.g. "x-someMetaInfo". Over time, non-standard struct members can be included into the standard, resulting in the "x-" prefix to be dropped.

The headers struct

The headers struct is sent as the first argument in every client request. It holds meta-data about the call, including the protocol version being used, authentication info and information about the client software. I leave it up for discussion whether authentication should be done by sending username and password for each request, sending a session cookie obtained from the server when logging in, or using HTTP authentication.

Client software recognition is done through appName and appVersion members in the headers struct. My guess is that this would basically do the same for Blogger as appKeys do now, and it would remove the overhead for both Pyra and client developers of handling appKeys. Additionally, clients would be recognizable to other services than Blogger. But of course it would be up to Pyra to decide if appKey was still required for Blogger as an x-appKey member in the headers struct.

The post struct

Another recurring data type in this proposal is the post struct, which holds the various parts that make a weblog post or story. What exactly the standard members of posts should be is open to discussion. I propose the following:

• title
• content
• categories (list of categories this post belongs to, if available)

So finally, here come the methods:

weblog.getUsersBlogs (headers) returns array

getUsersBlogs acts as a single stop sign in method, returning all the information about all the weblogs the user may post to. (Note: If we use a session scheme to handle authentication instead of username/password for each request, we must change the method to also return the session ID, or add a separate login method.) The return value is an array of structs with each struct describing a weblog. The weblog struct contains the following fields:

• id - the id of the weblog
• name - the weblog name
• url - the public url of the weblog
• categories - an array of strings containing the defined categories, if supported
• users - an array of strings containg the names of authors

weblog.getPostIndex (headers, blogid, filter) returns array

The getRecentPosts() method of the Blogger API is split into two methods: the getPostIndex method, that returns a "shallow" array of posts containing only the postid and the title of posts (or an equivalent short description) ordered by post date. (Question: should we add more fields than just id and title, maybe post date or author?)

This way, we can offer the users an overview of posts to edit without the overhead of actually transferring all the posts to the client. Only when a user acutally decides to edit a post is it fetched from the server using the getPost() method below. It should also be possible to retrieve several months or even years of blogging without putting to much stress on the server or bandwith.

Still, for pragmatical reasons, getPostIndex() by default only returns an index of recent posts (e.g. the last 20 ones). If clients wish to transfer other ranges of posts, they can be specified using the filter parameter which is a struct with the following members:

• username - retrieve only posts by this user
• category - retrieve only posts within this category
• beforeDate - retrieve only posts created before this date
• afterDate - retrieve only posts created after this date

weblog.getPost (headers, postid) returns struct

Retrieve a post from the server given a postid

(Question: should we include the blogid in addition to the postid in methods that act on a single post?)

weblog.newPost (headers, blogid, post, publish) returns string

Create a new post, optionally publishing it.

weblog.editPost (headers, postid, post, publish) returns boolean

Edit an existing post, optionally publishing it

weblog.deletePost (headers, postid) returns boolean

Delete a post.

That's it for a first rough sketch. Please let me know what you think!