RFC: MetaWeblog API

Document status 

This document was updated on 8/8/03, to incorporate all the RFCs related to the MetaWeblog API. The earlier version of the document is archived here. It has been reviewed by members of the MetaWeblog API mail list, and feedback has been incorporated.

On 8/24/03, I posted a last call for comments, and received several and incorporated some.

As of 8/26/03, this document is deployable. There may be changes, but they will be clearly documented, and will only clarify the spec, in no way will they change the format or protocol. It is now safe to deploy applications based on this spec.

What is the MetaWeblog API? 

The MetaWeblog API (MWA) is a programming interface that allows external programs to get and set the text and attributes of weblog posts. It builds on the popular XML-RPC communication protocol, with implementations available in many popular programming environments.

Relationship between MetaWeblog API and the Blogger API 

The MetaWeblog API is designed to enhance the Blogger API, which was limited in that it could only get and set the text of weblog posts. By the time MWA was introduced, in spring 2002, many weblog tools had more data stored with each post, and without an API that understood the extra data, content creation and editing tools could not access the data.

At the time of this writing, summer 2003, most popular weblog tools and editors support both the Blogger API and the MetaWeblog API.

Relationship between MetaWeblog API and RSS 2.0 

The MetaWeblog API uses an XML-RPC struct to represent a weblog post. Rather than invent a new vocabulary for the metadata of a weblog post, we use the vocabulary for an item in RSS 2.0. So you can refer to a post's title, link and description; or its author, comments, enclosure, guid, etc using the already-familiar names given to those elements in RSS 2.0. Further since RSS 2.0 is extensible, so is the MetaWeblog API. We have designed conventions for representing attributes and namespaces in MWA.

Basic entry-points 

There are three basic 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, as it is in the Blogger API, it's a struct. The defined members of struct are the elements of in RSS 2.0, providing a rich variety of item-level metadata, with well-understood applications.

The three basic elements are title, link and description. For blogging tools 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, named categories. On the server side, it's not an error if the category doesn't exist, only record categories for ones that do exist.

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.

In a call to metaWeblog.newPost or metaWeblog.editPost, if the struct contains a boolean named flNotOnHomePage, then the post does not appear on the home page, and only appears on the specified category pages.

Request and response 

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

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

metaWeblog.newMediaObject 

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

The blogid, username and password params are as in the Blogger API.

The struct must contain at least three elements, name, type and bits.

name is a string, it may be used to determine the name of the file that stores the object, or to display it in a list of objects. It determines how the weblog refers to the object. If the name is the same as an existing object stored in the weblog, it may replace the existing object.

type is a string, it indicates the type of the object, it's a standard MIME type, like audio/mpeg or image/jpeg or video/quicktime.

bits is a base64-encoded binary value containing the content of the object.

The struct may contain other elements, which may or may not be stored by the content management system.

If newMediaObject fails, it throws an error. If it succeeds, it returns a struct, which must contain at least one element, url, which is the url through which the object can be accessed. It must be either an FTP or HTTP url.

metaWeblog.getCategories 

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 entry-point allows editing tools to offer category-routing as a feature.

metaWeblog.getRecentPosts 

metaWeblog.getRecentPosts (blogid, username, password, numberOfPosts) returns array of structs

Each struct represents a recent weblog post, containing the same information that a call to metaWeblog.getPost would return.

If numberOfPosts is 1, you get the most recent post. If it's 2 you also get the second most recent post, as the second array element. If numberOfPosts is greater than the number of posts in the weblog you get all the posts in the weblog.

Transmitting elements with attributes 

The members of the struct passed in newPost and editPost come from the elements of items in RSS 2.0. The most commonly used core elements have no attributes, so it's clear how to include them in the struct. However, some elements, such as source, enclosure and category, may have attributes and a value. Here are a simple set of rules for elements that have attributes and a value. Note that these rules do not apply to enclosure and source, which are provided for specifically above.

1. If an element has attributes, then represent the element with a struct, and include the attributes as sub-elements of the struct.

2. If an element has both attributes and a value, make the element a struct, include the attributes as sub-elements, and create a sub-element for the value with the name _value. Note that this means that no element can be passed through the API that has an attribute whose name is _value.

Transmitting elements from namespaces 

RSS 2.0 allows for the use of namespaces. If you wish to transmit an element that is part of a namespace include a sub-struct in the struct passed to newPost and editPost whose name is the URL that specifies the namespace. The sub-element(s) of the struct are the value(s) from the namespace that you wish to transmit.

Comments 

The Blogger API provides a parameter called appkey that allows vendors to assign a key to developers so they can track and possibly limit usage of the API for certain tools. The MetaWeblog API doesn't specifically provide a parameter for an appkey. Applications that wish to transmit an appkey should add an element to the struct called appkey and set its value to the appkey that should be associated with the call.

Applications should use the fault-response scheme defined by XML-RPC. For example, trying to create, get, or edit a post without a valid username-password should generate a fault. Client applications should display the error string, as appropriate, to the user, for example, in a dialog, or in a server log.

Thanks 

Thanks to Michael Bernstein for help editing this spec in summer 2003.

References 

RSS 2.0; Dave Winer; 9/02.

RFC: MetaWeblog API; Dave Winer; 3/02.

Blogger API; Evan Williams; 8/01.

ManilaRPC; Andre Radke, Brent Simmons, Dave Winer; 1999.

XML-RPC; Dave Winer; 1998