Archived version of RFC:MetaWeblog API

Thu, Mar 14, 2002; by Dave Winer.

This is an archive of the MetaWeblog RFC as it existed on August 8, 2003. It's been superceded by a new RFC, that gathers all the RFCs linked into this document into a single-page spec.

At the beginning of this week I thought we'd do a little work and teach Radio 8 how to do titles and links in weblog posts. One thing led to another and now it's time to broaden the XML-RPC pipe that tools use to connect to Radio, and in doing so offer an evolution to the art of scripting weblog tools.

Background 

Manila has Manila-RPC, which is still the biggest API in blogging land. The Blogger API came along last summer and because of its simplicity and the popularity of Blogger, it was an instant hit. We supported it without a second thought.

But the Blogger API has a very simple idea of what a blog post is. It's basically a string. At the same time the blogging tools have matured, and a deeper API was needed. That became immediately evident as soon as we shipped Titles and Links in Radio. The Blogger API is too narrow to carry the new data. People who develop tools said let's have more. I gave it some thought and decided yes, let's do that.

What to call it? 

I could have tried to shoehorn these features into the Blogger API, I gave it some thought -- how about encoding the data somehow in the content param? Or klooge it up with the appKey param? Nahh. None of those approaches made any sense. The Blogger API is Evan's creation, if he chooses to move the spec forward, that's his choice. It's okay with me if these ideas appear in a future version of the Blogger API.

So as I was building the spec and an implementation in Radio 8, I had to come up with a new name. I thought maybe I should call it BiggerBlogger because that sounds kind of cool, but that's too close to Blogger. Could be confusing. So I asked what makes this thing different?

Metadata 

A totally over-used term, but that's what's going on here. This API views a post as a package of metadata with some well-known names and room to grow on an organized or an ad hoc basis. In my experience those are the kinds of APIs that have legs. They go somewhere.

So let's call this the MetaWeblog API.

Three entry-points 

There are three entry-points in the API:

metaWeblog.newPost (blogid, username, password, struct, publish) returns string

metaWeblog.editPost (postid, username, password, struct, publish) returns true

metaWeblog.getPost (postid, username, password) returns struct

The blogid, username, password and publish params are as in the Blogger API. newPost returns a string representation of the post id, again as defined by the Blogger API. The struct is where the juice is.

The struct 

In newPost and editPost, content is not a string, it's a struct. The defined members of struct are the elements of <item> in RSS 2.0, providing a rich variety of item-level metadata, with well-understood applications. It's also nice for UserLand because Radio supports all of this stuff.

The three basic elements are title, link and description. For a blogging tool that don't support titles and links, the description element holds what the Blogger API refers to as "content."

Where an element has attributes, for example, enclosure, pass a struct with sub-elements whose names match the names of the attributes according to the RSS 2.0 spec, url, length and type.

For the source element, pass a struct with sub-elements, url and name.

For categories, pass an array of strings of names of categories that the post belongs to. Sorry we don't pass through domains through this interface. In the Radio 8 implementation it's not an error if the category doesn't exist, but we will only record categories that do.

In getPost, the returned value is a struct, as with the Blogger API, but it contains extra elements corresponding to the struct passed to newPost and editPost.

The server must ignore all elements that it doesn't understand.

Request and response 

Here's an example of a request and a response.

Here's the post that this request is getting info about.

Update 5/7/03 -- Rounding out the API 

New RFC. With Blogger abandoning the original Blogger API, in favor of a new one that is not backward compatible, the MetaWeblog API is extended to include the calls that were previously not included in the MetaWeblog API. After a brief comment period, we'll rewrite the spec to document all the changes.

Update 1/12/03 -- How to transmit complex RSS 2.0 elements 

Published an RFC that explains how to transmit RSS 2.0 elements that have both attributes and a value.

Update 1/10/03 -- Started mail list, New entry point 

A new mail list for developers to discuss implementing and moving forward the MetaWeblog API

A new entry-point, metaWeblog.newMediaObject.

Update 11/14/02 -- Permit use of RSS 2.0 elements 

The defined members of the struct are the elements of <item> in RSS 2.0. Previously they had come from RSS 0.92.

Update 6/10/02 -- Radio implementation returns permalink 

In the Radio implementation, the struct returned from metaWeblog.getPost now includes a string called permaLink, which contains the URL of the post. This is useful for tools that want to provide a simple interface for connecting the editable post with the publicly visible post.

Update 3/18/02 -- Radio 8 support released 

The MetaWeblog API is now part of the official release of Radio 8.

Update 3/16/02 -- Added metaWeblog.getCategories. 

There was no way to get a list of categories for a weblog, now there is.

metaWeblog.getCategories (blogid, username, password) returns struct

The struct returned contains one struct for each category, containing the following elements: description, htmlUrl and rssUrl.

This call allows editing tools to offer category-routing as a feature.

Update 3/16/02 -- flNotOnHomePage 

metaWeblog.newPost and metaWeblog.editPost allow you to route posts to categories, but as specified yesterday, they don't allow you to exclude a post from the weblog home page. This is important functionality and should pass through the API.

With today's change, if the struct contains a boolean named flNotOnHomePage, then the post does not appear on the home page, and only appears on the category pages.

Update 3/16/02 -- publishing categories 

In yesterday's code release, only the home page would be published. That's fixed now -- if a post appears in categories, those categories are also published if we're instructed to publish.

Update 3/16/02 -- callback in Radio 8 implementation 

Per Garth Kidd's request, I added a callback that runs just before newPost and editPost process the incoming struct. The scripts reside in weblogData.callbacks.metaWeblogCopyFromStruct. Each script is passed an address of the struct and the address of the post table that it's to be copied into. The callbacks run before we copy, so they can modify the contents of the struct.