Blogger API Overview

The Blogger Data API allows client applications to view and update Blogger content in the form of Google Data API feeds. Your client application can use the Data API to create new blog posts, edit or delete existing posts, and query for posts that match particular criteria.

Here are some of the things you can do with the Blogger Data API:

* Add a running list of blog posts and comments to a site.
* Create a desktop application or plugin that allows users to create and post entries from the desktop.
* Create a blog aggregator application.


How do I start?

If you're new to the Blogger Data API, here's how we recommend you get started:

1. Get familiar with the Google Data APIs.
2. Read the Blogger Data API Developer's Guide.
3. Refer to the Reference Guide as needed.

Protocol Basics

This document describes the basics of the Google Data Protocol used by many Google APIs, including examples of what a query looks like, what results look like, and so on.

For more information about the Google Data Protocol, see the Developer's Guide overview page and the Protocol Reference.
Contents

1. Audience
2. Examples
1. Requesting a feed or other resource
2. Inserting a new entry
3. Searching for a string
4. Updating an entry
5. Deleting an entry
6. Requesting partial feeds or entries (Experimental ) New!
7. Updating specific fields (Experimental ) New!
3. Additional resources

Audience

This document is intended for anyone wanting to understand the general idea of the XML format and protocol used by the Google Data APIs.

Even if you just want to write code that uses the language-specific client libraries, you might want to read this document, to understand what's going on beneath the client-library abstraction layer.

This document assumes that you understand the basics of XML, namespaces, syndicated feeds, and the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional resources section of this document.

This document doesn't rely on any particular programming language; your client can interact with the server using any programming language that lets you issue HTTP requests and parse XML-based responses.

If you want to try the examples in this document without writing any code, you may find the command-line utilities cURL or Wget useful; for more information, see the manual pages for those utilities or the document on Using cURL to interact with services that use the Google Data Protocol.
Examples

The following examples show HTTP requests you might send to a generic service using the Google Data Protocol API protocol directly, and the results you might receive. For examples of how to send the requests using various programming languages, see the language-specific samples and client libraries. For information about using the Google Data Protocol with specific Google services, see the service-specific documentation.
Requesting a feed or other resource

Assume there's a feed called /myFeed, and assume that it currently doesn't happen to contain any entries. To see it, send the following HTTP request to the server:

GET /myFeed

The server responds:

200 OK


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>

2006-01-23T16:25:00-08:00
http://www.example.com/myFeed

Jo March




Note that although the feed doesn't contain any entries, it does contain metadata, such as a title and an author's name. It also contains a version identifier, in the form of an HTTP ETag.
Inserting a new entry

To create a new entry, send a POST request, and supply the XML representation of the new entry:

POST /myFeed




Elizabeth Bennet
liz@gmail.com


This is my entry


Note that you don't supply the standard Atom , , or elements; the server creates those in response to your POST request. Also note that the author of a feed doesn't have to be the same person as the author of an entry.

The server responds:

201 CREATED


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
http://www.example.com/id/1

2006-01-23T16:26:03-08:00

Elizabeth Bennet
liz@gmail.com


This is my entry


Searching for a string

To do a full-text search for a particular string, when using a service that supports full-text searches, send a GET request with the q parameter. For more information about query parameters, see Query requests in the protocol reference document.

GET /myFeed?q=This

The server responds with a feed containing all the entries that match the search string This. (In this case there's only one.)

200 OK


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>

2006-01-23T16:26:03-08:00
http://www.example.com/myFeed

Jo March



http://www.example.com/id/1

2006-01-23T16:26:03-08:00

Elizabeth Bennet
liz@gmail.com


This is my entry



Updating an entry

To update an existing entry, you need to do the following steps.

1. Retrieve the entry you want to update.
2. Modify it as desired.
3. Send a PUT request, with the updated entry in the message body, to the entry's edit URI. The edit URI appears in the previous example as the href attribute of the element.

You also have to specify the original entry's ETag, to ensure that you don't overwrite anyone else's changes.

In the following example, we're changing the entry's text from its old value ("This is my entry") to a new value ("This is my first entry."):

PUT /myFeed/1/1/


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
http://www.example.com/id/1

2006-01-23T16:28:05-08:00

Elizabeth Bennet
liz@gmail.com


This is my first entry.


The server responds:

200 OK


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
http://www.example.com/id/1

2006-01-23T16:28:05-08:00

Elizabeth Bennet
liz@gmail.com


This is my first entry.


Note that the ETag has changed. For more information about versions of resources, see the Resource versioning (ETags) section of the protocol reference document.

To see the new entry in context, request the entire resource again:

GET /myFeed

The server responds:

200 OK


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>

2006-01-23T16:28:05-08:00
http://www.example.com/myFeed

Jo March



http://www.example.com/id/1

2006-01-23T16:28:05-08:00

Elizabeth Bennet
liz@gmail.com


This is my first entry.




Note: If your firewall does not allow PUT, then do an HTTP POST and set the method override header as follows:

X-HTTP-Method-Override: PUT

Deleting an entry

To delete an existing entry, send a DELETE request, using the entry's edit URI (as provided by the server in the previous example).

If your firewall does not allow DELETE, then do an HTTP POST and set the method override header as follows:

X-HTTP-Method-Override: DELETE

When you delete an entry, you can choose whether to do a conditional delete (only delete if the entry hasn't changed since last time you retrieved it) or an unconditional delete. For more information, see the Resource versioning (ETags) section of the protocol reference document. To do an unconditional delete, set the following HTTP header:

If-Match: *

The following example deletes an entry (if headers are set appropriately):

DELETE /myFeed/1/

The server responds:

200 OK

Do another GET to see that the feed now contains no entries:

GET /myFeed

The server responds with a feed that contains nothing but metadata:

200 OK


xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>

2006-01-23T16:30:11-08:00
http://www.example.com/myFeed

Jo March




If the deletion fails, then the server responds with an error code. For more information, see HTTP status codes in the protocol reference document.
Requesting partial feeds or entries (Experimental )

In contrast to the simple example feed shown in this document, in practice, feeds can be quite complex. With some APIs, you can ask for only the elements or attributes of interest, instead of the full resource representation. When you avoid retrieving and parsing unneeded data, you can significantly improve the efficiency of your client application.

To request a partial response, use the fields query parameter to specify which elements or attributes you want returned. For more information, see Partial response in the protocol reference document.

The following example requests only the feed ID, and the author and title for each feed entry,

GET /myFeed?fields=id,entry(author)

The server responds:

200 OK


xmlns:gd='http://schemas.google.com/g/2005'>
http://www.example.com/myFeed


Elizabeth Bennet
liz@gmail.com





Elizabeth Bennet
liz@gmail.com





You can use the fields parameter with any kind of request that returns data. In addition to GET, this includes POST, and PUT (as well as PATCH, which is used for making partial update requests).

Note: The fields query parameter only controls the data sent back in response to a request; it does not affect the data that you must provide in the body of a PUT, POST, or PATCH request.

Examples for POST and PUT are shown below.

* When you make a POST request for a partial response, you must still provide the same data as described in Inserting a new entry. The following example requests a partial response that contains only the title of the newly created entry:

POST /myFeed?fields=title

...data...

The server responds:

200 OK






* When you make a PUT request for a partial response, you must still provide a modified version of the full resource representation, as described in Updating an entry. The following example requests a partial response that contains only the new ETag value of the modified entry:

PUT /myFeed/1/1?fields=@gd:etag

...data...

The server responds:

200 OK


gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Updating specific fields (Experimental )

If the API you are using supports partial response and has editable fields, you can also avoid sending unnecessary data when modifying an entry. Partial update allows you to send data only for the fields that you want to change.

To use partial update, you send a PATCH request to the same edit URI you use with PUT. The data that you send with PATCH must follow certain conventions. However, the semantics are flexible enough for you to replace data in the target resource, add to it, or even make deletions from it, all with a single request.

Note: As with PUT, you have to specify the original entry's ETag, to make sure you don't overwite anyone else's changes.

For more information on PATCH and its semantics, see Partial update in the protocol reference document.

This example shows a partial update request that modifies the entry's title:

PATCH /myfeed/1/1/

xmlns:gd='http://schemas.google.com/g/2005'
gd:etag="EksPTg1Bfyp7IWA6WhJT"
gd:fields='title'>



When the server receives a PATCH request, it first removes any fields specified by the entry's gd:fields attribute (if present); then it merges any data provided in the request body with the target resource. In this example, the title element is first removed from the target resource; then the new title value is merged. Effectively, this request replaces the old title with the new one.

Note, however, that the semantics of PATCH are to merge the partial representation into the existing resource. You don't always have to remove a field to update its value.

* If field can only exist once in the target entry then, on merging, the field in the partial representation overwrites the corresponding field in the target entry.
* If the field can exist more than once in the target entry then, on merging, the partial field is added to the target entry.

The difference between how repeating and non-repeating fields are merged is shown by the next example, which adds a new title and author to the entry without using the gd:fields attribute to remove either of them first.

PATCH /myfeed/1/1/

xmlns:gd='http://schemas.google.com/g/2005'
gd:edtag="EksPTg1Bfyp7IWA6WhJT">


Fitzwilliam Darcy
darcy@gmail.com



Since the partial entry representation has no gd:fields attribute, no fields are removed. However, the new values for the