Blogger API 2.0 documentation (Developer Preview, Draft, Feb 3 2003)

Alert This documentation is provided for historical interest only. The Blogger 2.0 API no longer functions on Blogger.com. Please use our GData API. — phopkins, 4/2007

Blogger API 2.0 documentation (Developer Preview, Draft, Feb 3, 2003)

-ev williams
-steve jenson
(with special thanks to John Magdziarz)

A Note on Types

Method Signatures

Core Datastructures

Basic Mapping of 1.0 to 2.0

Future of the API

A Note on Types

All types shown are XML-RPC types except for Booleans, where I say Boolean.TRUE and Boolean.FALSE. XML-RPC types will map locally to different types for different languages or different toolkits.

Method Signatures

blogger2.newPost(Struct login, Struct post, Struct actions) => String postid
blogger2.editPost(Struct login, Struct post, Struct actions) => Boolean success
blogger2.deletePost(Struct login, Struct post, Struct actions) => Boolean success

blogger2.getPost(Struct login, Struct post [only postid and blogid are needed or paid attention to]) => Struct post
blogger2.getPosts(Struct login, String blogID, Struct filters) => Array of Struct post's, unordered
blogger2.getBlogs(Struct login) => Array of Struct blogs

blogger2.getTemplate(Struct login, String blogID, String templateName) => Array of Struct template, unordered
blogger2.setTemplate(Struct login, String blogID, Array of Struct template) => Boolean success
blogger2.getTemplates(Struct login, String blogID) => Array of Struct template, unordered

blogger2.getUserInfo(Struct login) => Struct user
blogger2.setUserInfo(Struct login, Struct user) => Boolean success

blogger2.getBlogCategories(Struct login, String blogID) => Array of Strings
blogger2.setBlogCategories(Struct login, String blogID, Array categories) => Array of Strings

blogger2.publish(Struct login, String blogID) => Boolean

We also support the proposed server introspection api

Core Datastructures

Struct 'login':

username -> String password -> String appkey -> String clientID -> String token -> String (not implemented yet. will be addressed with the blogger2.secure.* module)

Struct 'post':

postID -> String blogID -> String body -> String dateCreated -> dateTime.iso8601postOptions -> Struct

Struct 'blog':

blogID -> String url -> String blogName -> String

Struct 'template':

id -> String name -> String body -> String type -> String

Struct 'filters':

startDate -> dateTime.iso8601 endDate -> dateTime.iso8601 onDate -> dateTime.iso8601 postIDStart -> String postIDEnd -> String rangeStart -> int rangeEnd -> int postID -> String multiplePostIDs -> Array of Strings returnAllPosts -> Boolean includeDraftPosts -> Boolean includeFuturePosts -> Boolean numOfPosts -> Integer returnOnlyPostIDs -> Boolean

Struct 'actions':

doPublish -> Boolean makeDraft -> Boolean syndicate -> Boolean allowComments -> Boolean (not implemented yet)

Struct 'user':

username -> String firstName -> String lastName -> String email -> String pid -> int

Struct 'postOptions':

categories -> Array of Strings title -> String permalinkUrl -> String relatedUrl -> String convertLineBreaks -> String

The difference between Filters and Actions is that Filters determine the information you get back from requests while Actions determine how the data you give to Blogger in an API request will be handled.

Filters precedence

If postID is by itself, that post is returned.
If multiplePostIDs is sent, then those posts are returned
If postID is sent along with multiplePostids, then the two are combined into one array and those Posts are returned.
If returnAllPosts is set to Boolean.TRUE then every post belonging to this blog, including drafts, are returned.
If postIDStart and postIDEnd are both sent then all post's between those two postIDs will be returned inclusively.

If startDate is by itself then all posts from that date until the current date are returned inclusively.
If endDate is by itself then all posts from the start of the blog until that date are returned inclusively.
If startDate and endDate are combined then posts inclusively between those two dates are returned.
If onDate is sent with no other date filters then all posts on that date are returned.
If onDate is combined with either startDate or endDate then onDate is ignored.

includeDraftPosts applies to any post sent back. If includeDraftPosts isn't sent, then it's value is 'False'
If rangeStart and rangeEnd are both sent, then you would be returned posts within that range. This is not a postid number, this is an index. An example of this would be if you were to send rangeStart=>0 and rangeEnd=>10 then you would be returned the 0th to the 10th post.

If numOfPosts is sent then you are only returned this many last posts. If there are no other filters sent, this is set to 20, otherwise it is has no default value.

If returnOnlyPostIDs is set to true, then only the posts are returned. This is assumed to be false if not set.

Basic Mapping of API 1.0 to 2.0

For existing implementors of API 1.0, we feel the following conceptual mapping should prove helpful for converting apps:

Creating a new post:


  API 1.0:
	blogger.newPost("BIGHONKINGAPPKEY","stevej","myfakepassword","3187374","hi, uncle leo!", Boolean.TRUE)

  API 2.0:
	blogger2.newPost([["appkey" => "BIGHONKINGAPPKEY"], [["blogID" => "3187374"],     [["doPublish" => Boolean.TRUE]])
			  ["username" => "stevej"]           ["body" => "hi, uncle leo!"]]
                          ["password" => "myfakepassword"]]

Getting a group of posts:


  API 1.0:
	blogger.getRecentPosts("BIGHONKINGAPPKEY","3187374","stevej","myfakepassword", 20);
	
  API 2.0:
	blogger2.getRecentPosts([["appkey" => "BIGHONKINGAPPKEY"], [["blogID" => "3187374"]], [["numOfPosts" => 20]])
                                 ["username" => "stevej"]                                                                             
                                 ["password" => "myfakepassword"]]

Getting a user's information:


  API 1.0:
	blogger.getUserInfo("BIGHONKINGAPPKEY","stevej","myfakepassword")

  API 2.0:
 	blogger2.getUserInfo([["appkey" => "BIGHONKINGAPPKEY"]
		              ["username" => "stevej"]
                              ["password" => "myfakepassword"]])

We think you'll find the new api style to be much more expressive, especially for new tool developers.

Future of the API

New filters and actions for more powerful interactions between external clients and Blogger. Modules for handling your settings, playing with your stats, etc.