Blogger Api -- 小米规整

发表于 更新于 分类于
本文字数： 49k 阅读时长 ≈ 44 分钟
分享下 Blogger Api 希望大家喜欢

Blogger API: Getting Started

This document explains how to get started using the Blogger API.

Before you start

Get a Google Account

Make sure that you have a Google Account set up. We recommend that you use a separate Google Account for development and testing purposes to protect yourself from accidental data loss. If you already have a test account, then you’re all set; you can visit the Blogger user interface to set up, edit, or view your test data.

Get familiar with Blogger

If you’re unfamiliar with Blogger concepts, read this document and experiment with the user interface before starting to code. This document assumes that you’re familiar with Blogger, with web programming concepts, and with web data formats.

Learn about authorizing requests and identifying your application

When your application requests private data, the request must be authorized by an authenticated user who has access to that data.

When your application requests public data, the request doesn’t need to be authorized, but does need to be accompanied by an identifier, such as an API key.

For information about how to authorize requests and use API keys, see Authorizing requests and identifying your application in the Using the API document.

Blogger API background

Blogger concepts

Blogger is built on five basic concepts:

  • Blogs: The root concept of the API. A blog has posts and pages. This is the container for blog meta-information like blog name and Description.
  • Posts: A blog post is the publishable item that the blog author has created. This information is meant to be timely, reflecting what the authors want to publish to the world now. It is understood that as time passes, blog posts content ages and becomes less relevent.
  • Comments: A comment is the place where people other than the blog post author react to what the author has written. Everything from bricks to bouquets.
  • Pages: A page is a place for static content, such as biographical information, or the ways to contact the user. This is generally timeless information that doesn’t change very often.
  • Users: A user is someone who interacts with Blogger, be they acting as an Author, an Administrator, or just a Reader. For public blogs, readers may be anonymous, but on private blogs a reader must be identified by Blogger.

Blogger API data model

A resource is an individual data entity with a unique identifier. The Blogger JSON API operates on five types of resources:

  • Blogs resource: Represents a blog.
  • Posts resource: Represents a post; each posts resource is a child of a blogs resource.
  • Comments resource: Represents a comment on a specific post; each comments resource is a child of a posts resource.
  • Pages resource: Represents a static page; each pages resource is a child of a blogs resource.
  • Users resource: Represents a non-anonymous user. This is used to identify the Author of a page, post, or comment.

The blogs resource has two children resource types, pages and posts. A posts resource may have comments resource children.

Overview of the relationships between resources

The Blogger API data model is based on groups of resources, called collections:

Blogs collection

A blogs collection consists of all the blogs a user has access rights to. You can list blogs by user, or retrieve a single blog by ID.

Posts collection

A Posts collection consists of all the posts resources within a specific blogs resource.

Comments collection

A comments collection consists of all the comments resources within a specific posts resource.

Pages collection

A pages collection consists of all the pages resources within a specific blogs resource.

Users Collection

A users collection consists of all the users resources on Blogger, and thus cannot be listed. A user can retrieve their own users resource (but nobody else’s) by ID, or by using the identifier self.

Blogger API operations

You can invoke a number of different methods on collections and resources in the Blogger API, as described in the following table.

Operation Description REST HTTP mappings
list Lists all resources within a collection. GET on a collection URI.
get Gets a specific resource. GET on a resource URI.
getByUrl Gets a resource, looking it up by URL. GET with the URL passed in as a parameter.
getByPath Gets a resource by looking it up by its path. GET with the Path passed in as a parameter.
listByUser Lists resources owned by a User. GET on a user owned collection.
search Search for resources, based on a query parameter. GET on a Search URL, with the query passed in as a parameter.
insert Create a resource in a collection. POST on a collection URI.
delete Deletes a resource. DELETE on a resource URI.
patch Update a resource, using Patch semantics. PATCH on a resource URI.
update Update a resource. PUT on a resource URI.

The table below shows which methods are supported by each resource type. All list and get operations on private blogs require authentication.

Resource Type list get getByUrl getByPath listByUser search insert delete patch update
Blogs no yes yes no yes no no no no no
Posts yes yes no yes no yes yes yes yes yes
Comments yes yes no no no no no no no no
Pages yes yes no no no no no no no no
Users no yes no no no no no no no no

Calling styles

There are several ways to invoke the API:

  • Using REST directly or from JavaScript (no server-side code required)
  • Using the client libraries.

REST

REST is a style of software architecture that provides a convenient and consistent approach to requesting and modifying data.

The term REST is short for “Representational State Transfer.” In the context of Google APIs, it refers to using HTTP verbs to retrieve and modify representations of data stored by Google.

In a RESTful system, resources are stored in a data store; a client sends a request that the server perform a particular action (such as creating, retrieving, updating, or deleting a resource), and the server performs the action and sends a response, often in the form of a representation of the specified resource.

In Google’s RESTful APIs, the client specifies an action using an HTTP verb such as POST, GET, PUT, or DELETE. It specifies a resource by a globally-unique URI of the following form:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Because all API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the web’s distributed infrastructure.

You may find the method definitions in the HTTP 1.1 standards documentation useful; they include specifications for GET, POST, PUT, and DELETE.

REST in the Blogger API

The supported Blogger operations map directly to REST HTTP verbs, as described in Blogger API operations.

The specific format for Blogger API URIs are:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

The full explanation of URIs used and the results for each supported operation in the API is summarized in the Blogger API Reference document.

Examples

List the blogs that the authenticated user has access rights to:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

Get the posts on the code.blogger.com blog, which has blog ID 3213900:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST from JavaScript

You can invoke the Blogger API from JavaScript, using the callback query parameter and by providing a callback function. When the browser loads the script, the callback function is executed and the response is provided to the callback function. This approach allows you to write rich applications that display Blogger data without requiring server side code.

The following example retrieves a post from the code.blogger.com blog, after you replace YOUR-API-KEY with your API key.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

Data format

JSON

JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.

Blogger API: Using the API

The Blogger API enables you to integrate Blogger content with your application by using the REST APIs. Before you begin, you will need to set up authorization.

Introduction

This document is intended for developers who want to write applications that can interact with the Blogger API. Blogger is a tool for creating websites that allow people to publish their thoughts on an ongoing basis.

If you’re unfamiliar with Blogger concepts, you should read Getting Started before starting to code.

Authorizing requests and identifying your application

Every request your application sends to the Blogger APIs needs to identify your application to Google. There are two ways to identify your application: using an OAuth 2.0 token (which also authorizes the request) and/or using the application’s API key. Here’s how to determine which of those options to use:

If the request requires authorization (such as a request for an individual’s private data), then the application must provide an OAuth 2.0 token with the request. The application may also provide the API key, but it doesn’t have to.
If the request doesn’t require authorization (such as a request for public data), then the application must provide either the API key or an OAuth 2.0 token, or both—whatever option is most convenient for you.

About authorization protocols

Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported. If your application uses Google Sign-In, some aspects of authorization are handled for you.

Authorizing requests with OAuth 2.0

Requests to the Blogger APIs for non-public user data must be authorized by an authenticated user.

This process is facilitated with an OAuth client ID.

GET AN OAUTH CLIENT ID
Or create one in the Credentials page.

The details of the authorization process, or “flow,” for OAuth 2.0 vary somewhat depending on what kind of application you’re writing. The following general process applies to all application types:

When your application needs access to user data, it asks Google for a particular scope of access.
Google displays a consent screen to the user, asking them to authorize your application to request some of their data.
If the user approves, then Google gives your application a short-lived access token.
Your application requests user data, attaching the access token to the request.
If Google determines that your request and the token are valid, it returns the requested data.
Some flows include additional steps, such as using refresh tokens to acquire new access tokens. For detailed information about flows for various types of applications, see Google’s OAuth 2.0 documentation.

Here’s the OAuth 2.0 scope information for the Blogger APIs:

https://www.googleapis.com/auth/blogger

To request access using OAuth 2.0, your application needs the scope information, as well as information that Google supplies when you register your application (such as the client ID and the client secret).

Tip: The Google APIs client libraries can handle some of the authorization process for you. They are available for a variety of programming languages; check the page with libraries and samples for more details.

Acquiring and using an API key

Requests to the Blogger APIs for public data must be accompanied by an identifier, which can be an API key or an access token.

GET A KEY
Or create one in the Credentials page.

After you have an API key, your application can append the query parameter key=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn’t need any encoding.

Working with blogs

Retrieving a blog

You can retrieve information for a particular blog by sending an HTTP GET request to the blog’s URI. The URI for a blog has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId

Request

GET https://www.googleapis.com/blogger/v3/blogs/2399953?key=YOUR-API-KEY

A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the blog data:

{
  "kind": "blogger#blog",
  "id": "2399953",
  "name": "Blogger Buzz",
  "description": "The Official Buzz from Blogger at Google",
  "published": "2007-04-23T22:17:29.261Z",
  "updated": "2011-08-02T06:01:15.941Z",
  "url": "http://buzz.blogger.com/",
  "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953",
  "posts": {
    "totalItems": 494,
    "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/posts"
  },
  "pages": {
    "totalItems": 2,
    "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/pages"
  },
  "locale": {
    "language": "en",
    "country": "",
    "variant": ""
  }
}

Retrieving a blog by its URL

You can retrieve a blog using its URL by sending an HTTP GET request to the following URI with a url parameter:

https://www.googleapis.com/blogger/v3/blogs/byurl?url=blog-url

Request

https://www.googleapis.com/blogger/v3/blogs/byurl?url=http://code.blogger.com/

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the full representation of the identified blog:

{
 "kind": "blogger#blog",
 "id": "3213900",
 "name": "Blogger Developers Network",
 "description": "The official Blogger Developers Network weblog.",
 "published": "2007-02-09T10:13:10-08:00",
 "updated": "2012-04-15T19:38:01-07:00",
 "url": "http://code.blogger.com/",
 "selfLink": "https://www.googleapis.com/blogger/v3/blogs/3213900",
 "posts": {
  "totalItems": 55,
  "selfLink": "https://www.googleapis.com/blogger/v3/blogs/3213900/posts"
 },
 "pages": {
  "totalItems": 1,
  "selfLink": "https://www.googleapis.com/blogger/v3/blogs/3213900/pages"
 },
 "locale": {
  "language": "en",
  "country": "US",
  "variant": ""
 }
}

Retrieving a user’s blogs

You can retrieve a list of a user’s blogs by sending an HTTP GET request to the blogs collection URI:

https://www.googleapis.com/blogger/v3/users/userId/blogs

Request

GET https://www.googleapis.com/blogger/v3/users/self/blogs

Authorization: /* OAuth 2.0 token here */
Note: The user must be authenticated to list their own blogs, so you must provide the Authorization HTTP header with the GET request.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the full representation of the list of the user’s blogs:

{
  "kind": "blogger#blogList",
  "items": [
    {
      "kind": "blogger#blog",
      "id": "4967929378133675647",
      "name": "Brett's Test Blawg",
      "description": "",
      "published": "2010-10-06T23:33:31.662Z",
      "updated": "2011-08-08T06:50:02.005Z",
      "url": "http://brettmorgan-test-blawg.blogspot.com/",
      "selfLink": "https://www.googleapis.com/blogger/v3/blogs/4967929378133675647",
      "posts": {
        "totalItems": 13,
        "selfLink": "https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/posts"
      },
      "pages": {
        "totalItems": 1,
        "selfLink": "https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/pages"
      },
      "locale": {
        "language": "en",
        "country": "",
        "variant": ""
      }
    }
  ]
}

Working with posts

Retrieving posts from a blog

You can retrieve a list of posts from a given blog by sending a GET request to the posts collection URI. The URI for a posts collection has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts

Request

Here is an example:

GET https://www.googleapis.com/blogger/v3/blogs/2399953/posts?key=YOUR-API-KEY

A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the list of posts:

{
  "kind": "blogger#postList",
  "nextPageToken": "CgkIChiAkceVjiYQ0b2SAQ",
  "prevPageToken": "CgkIChDBwrK3mCYQ0b2SAQ",
  "items": [
    {
      "kind": "blogger#post",
      "id": "7706273476706534553",
      "blog": {
        "id": "2399953"
      },
      "published": "2011-08-01T19:58:00.000Z",
      "updated": "2011-08-01T19:58:51.947Z",
      "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html",
      "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553",
      "title": "Latest updates, August 1st",
      "content": "elided for readability",
      "author": {
        "id": "401465483996",
        "displayName": "Brett Wiltshire",
        "url": "http://www.blogger.com/profile/01430672582309320414",
        "image": {
          "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png"
         }
      },
      "replies": {
        "totalItems": "0",
        "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553/comments"
      }
    },
    {
      "kind": "blogger#post",
      "id": "6069922188027612413",
      elided for readability
    }
  ]
}

Retrieving a specific post

You can retrieve a specific post from a blog by sending a GET request to the posts resource URI. The URI for a posts resource has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId

Request

GET https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553?key=YOUR-API-KEY

A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
  "kind": "blogger#post",
  "id": "7706273476706534553",
  "blog": {
    "id": "2399953"
  },
  "published": "2011-08-01T19:58:00.000Z",
  "updated": "2011-08-01T19:58:51.947Z",
  "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html",
  "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553",
  "title": "Latest updates, August 1st",
  "content": "elided for readability",
  "author": {
    "id": "401465483996",
    "displayName": "Brett Wiltshire",
    "url": "http://www.blogger.com/profile/01430672582309320414",
    "image": {
      "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png"
    }
  },
  "replies": {
    "totalItems": "0",
    "selfLink": "https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553/comments"
  }
}

Searching for a post

You can search for posts from a blog by sending a GET request to the post search URI with the q search query parameter:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search?q=query terms

Request

GET https://www.googleapis.com/blogger/v3/blogs/3213900/posts/search?q=documentation&key=YOUR-API-KEY

A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
  "kind": "blogger#postList",
  "nextPageToken": "CgkIChiAj86CpB8QzJTEAQ",
  "prevPageToken": "CgkIChDBq5v24yYQzJTEAQ",
  "items": [
  {
    "kind": "blogger#post",
    "id": "1387873546480002228",
    "blog": {
      "id": "3213900"
    },
    "published": "2012-03-23T01:58:00-07:00",
    "updated": "2012-03-23T01:58:12-07:00",
    "url": "http://code.blogger.com/2012/03/blogger-documentation-has-moved-to.html",
    "selfLink": "https://www.googleapis.com/blogger/v3/blogs/3213900/posts/1387873546480002228",
    "title": "Blogger Documentation has moved to developers.google.com",
    "content": "content elided for readability",
    "author": {
      "id": "16258312240222542576",
      "displayName": "Brett Morgan",
      "url": "http://www.blogger.com/profile/16258312240222542576",
      "image": {
        "url": "https://resources.blogblog.com/img/b16-rounded.gif"
      }
    },
    "replies": {
      "totalItems": "0",
      "selfLink": "https://www.googleapis.com/blogger/v3/blogs/3213900/posts/1387873546480002228/comments"
    }
  },
  ...
  ]
}

Adding a post

You can add a post for a blog by sending a POST request to the post collection URI with a post JSON body:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/

Request

POST https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/

Authorization: /* OAuth 2.0 token here */
Content-Type: application/json

{
  "kind": "blogger#post",
  "blog": {
    "id": "8070105920543249955"
  },
  "title": "A new post",
  "content": "With <b>exciting</b> content..."
}

You must be authenticated to create a post.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
“kind”: “blogger#post”,
“id”: “6819100329896798058”,
“blog”: {
“id”: “8070105920543249955”
},
“published”: “2012-05-20T20:08:00-07:00”,
“updated”: “2012-05-20T20:08:35-07:00”,
“url”: “http://brettmorgan-test2.blogspot.com/2012/05/new-post.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058",
“title”: “A new post”,
“content”: “With exciting content…”,
“author”: {
“id”: “16258312240222542576”,
“displayName”: “Brett Morgan”,
“url”: “http://www.blogger.com/profile/16258312240222542576",
“image”: {
“url”: “https://resources.blogblog.com/img/b16-rounded.gif"
}
},
“replies”: {
“totalItems”: “0”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058/comments"
}
}
Deleting a post
You can delete a post for a blog by sending a DELETE request to the post resource URI:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
Request
Here is an example:

DELETE https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058
Authorization: /* OAuth 2.0 token here */
You must be authenticated to delete a post.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code.

Retrieving a post by its path
You can retrieve a post from a blog by sending a GET request to the posts bypath URI with a path parameter. The URI for a posts by path request has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath?path=post-path
Request
https://www.googleapis.com/blogger/v3/blogs/2399953/posts/bypath?path=/2011/08/latest-updates-august-1st.html&key=YOUR-API-KEY
A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
“kind”: “blogger#post”,
“id”: “7706273476706534553”,
“blog”: {
“id”: “2399953”
},
“published”: “2011-08-01T19:58:00.000Z”,
“updated”: “2011-08-01T19:58:51.947Z”,
“url”: “http://buzz.blogger.com/2011/08/latest-updates-august-1st.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553",
“title”: “Latest updates, August 1st”,
“content”: “elided for readability”,
“author”: {
“id”: “401465483996”,
“displayName”: “Brett Wiltshire”,
“url”: “http://www.blogger.com/profile/01430672582309320414",
“image”: {
“url”: “http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png"
}
},
“replies”: {
“totalItems”: “0”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/2399953/posts/7706273476706534553/comments"
}
}
Updating a post
You can update a post for a blog by sending a PUT request to the post resource URI with a post JSON body:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
Request
PUT https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/3445355871727114160
Authorization: /* OAuth 2.0 token here */
Content-Type: application/json

{
“kind”: “blogger#post”,
“id”: “3445355871727114160”,
“blog”: {
“id”: “8070105920543249955”
},
“url”: “http://brettmorgan-test2.blogspot.com/2012/05/new-post_20.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/3445355871727114160",
“title”: “An updated post”,
“content”: “With really exciting content…”
}
You must be authenticated to update a post.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
“kind”: “blogger#post”,
“id”: “6819100329896798058”,
“blog”: {
“id”: “8070105920543249955”
},
“published”: “2012-05-20T20:08:00-07:00”,
“updated”: “2012-05-20T20:08:35-07:00”,
“url”: “http://brettmorgan-test2.blogspot.com/2012/05/new-post.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058",
“title”: “An updated post”,
“content”: “With really exciting content…”,
“author”: {
“id”: “16258312240222542576”,
“displayName”: “Brett Morgan”,
“url”: “http://www.blogger.com/profile/16258312240222542576",
“image”: {
“url”: “https://resources.blogblog.com/img/b16-rounded.gif"
}
},
“replies”: {
“totalItems”: “0”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058/comments"
}
}
Updating A post with patch semantics
You can update a post with patch semantics by sending a PATCH request to the post resource URI with a post JSON body:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
Request
Here is an example:

PATCH https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/3445355871727114160
Authorization: /* OAuth 2.0 token here */
Content-Type: application/json

{
“content”: “With absolutely fabulous content…”
}
You must be authenticated to update a post.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the contents of the post:

{
“kind”: “blogger#post”,
“id”: “6819100329896798058”,
“blog”: {
“id”: “8070105920543249955”
},
“published”: “2012-05-20T20:08:00-07:00”,
“updated”: “2012-05-20T20:08:35-07:00”,
“url”: “http://brettmorgan-test2.blogspot.com/2012/05/new-post.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058",
“title”: “An updated post”,
“content”: “With absolutely fabulous content…”,
“author”: {
“id”: “16258312240222542576”,
“displayName”: “Brett Morgan”,
“url”: “http://www.blogger.com/profile/16258312240222542576",
“image”: {
“url”: “https://resources.blogblog.com/img/b16-rounded.gif"
}
},
“replies”: {
“totalItems”: “0”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/8070105920543249955/posts/6819100329896798058/comments"
}
}
Working with comments
Retrieving comments for a post
You can retrieve a list of comments for a post by sending a GET request to the comments collection URI. The URI for a comments collection has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
Request
GET https://www.googleapis.com/blogger/v3/blogs/2399953/posts/6069922188027612413/comments?key=YOUR-API-KEY
“A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the list of comments:

{
“kind”: “blogger#commentList”,
“nextPageToken”: “CgkIFBDwjvDXlyYQ0b2SARj9mZe9n8KsnlQ”,
“prevPageToken”: “CgkIFBisvMGRlyYQ0b2SARj9mZe9n8KsnlQ”,
“items”: [
{
“kind”: “blogger#comment”,
“id”: “9200761938824362519”,
“post”: {
“id”: “6069922188027612413”
},
“blog”: {
“id”: “2399953”
},
“published”: “2011-07-28T19:19:57.740Z”,
“updated”: “2011-07-28T21:29:42.015Z”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519",
“content”: “elided”,
“author”: {
“id”: “530579030283”,
“displayName”: “elided”,
“url”: “elided”,
“image”: {
“url”: “elided”
}
}
},
{
“kind”: “blogger#comment”,
“id”: “400101178920857170”,
elided for readability
}
]
}
Retrieving a specific comment
You can retrieve a specific comment from a post by sending a GET request to the comments resource URI. The URI for a comments resource has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
Request
GET https://www.googleapis.com/blogger/v3/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519?key=YOUR-API-KEY
“A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the comment data:

{
“kind”: “blogger#comment”,
“id”: “9200761938824362519”,
“post”: {
“id”: “6069922188027612413”
},
“blog”: {
“id”: “2399953”
},
“published”: “2011-07-28T19:19:57.740Z”,
“updated”: “2011-07-28T21:29:42.015Z”,
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519",
“content”: “elided”,
“author”: {
“id”: “530579030283”,
“displayName”: “elided”,
“url”: “elided”,
“image”: {
“url”: “elided”
}
}
}
Working with pages
Retrieving pages for a blog
You can retrieve a list of pages for a blog by sending a GET request to the pages collection URI. The URI for a pages collection has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/pages
Request
GET https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/pages?key=YOUR-API-KEY
“A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the list of pages:

{
“kind”: “blogger#pageList”,
“items”: [
{
“kind”: “blogger#page”,
“id”: “273541696466681878”,
“blog”: {
“id”: “4967929378133675647”
},
“published”: “2011-07-14T16:16:00.000Z”,
“updated”: “2011-07-14T16:16:23.602Z”,
“url”: “http://brettmorgan-test-blawg.blogspot.com/p/static-content.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/pages/273541696466681878",
“title”: “Static Content”,
“content”: “elided for readability”,
“author”: {
“id”: “901569848744”,
“displayName”: “brett”,
“url”: “http://www.blogger.com/profile/16258312240222542576",
“image”: {
“url”: “https://resources.blogblog.com/img/b16-rounded.gif"
}
}
}
]
}
Retrieving a specific page
You can retrieve a specific page from a blog by sending a GET request to the pages resource URI. The URI for a pages Resource has the following format:

https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId
Request
GET https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/pages/273541696466681878?key=YOUR-API-KEY
“A user does not need to be authenticated to retrieve a public blog. The application does not need to include Authorization HTTP header for a public blog request; however, you do need to provide the API key.

Blogger also has private blogs, which require authentication.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and the page data:

{
“kind”: “blogger#page”,
“id”: “273541696466681878”,
“blog”: {
“id”: “4967929378133675647”
},
“published”: “2011-07-14T16:16:00.000Z”,
“updated”: “2011-07-14T16:16:23.602Z”,
“url”: “http://brettmorgan-test-blawg.blogspot.com/p/static-content.html",
“selfLink”: “https://www.googleapis.com/blogger/v3/blogs/4967929378133675647/pages/273541696466681878",
“title”: “Static Content”,
“content”: “elided for readability”,
“author”: {
“id”: “901569848744”,
“displayName”: “brett”,
“url”: “http://www.blogger.com/profile/16258312240222542576",
“image”: {
“url”: “https://resources.blogblog.com/img/b16-rounded.gif"
}
}
}
Working with users
Retrieving a user
You can retrieve a user’s information by sending an HTTP GET request to the users resource URI:

https://www.googleapis.com/blogger/v3/users/userId
Request
GET https://www.googleapis.com/blogger/v3/users/self
Authorization: /* OAuth 2.0 token here */
Note: The user must be authenticated to list their own information, so you must provide the Authorization HTTP header with the GET request.

Response
If the request succeeds, the server responds with an HTTP 200 OK status code and a link to a list of the user’s blogs:

{
“kind”: “blogger#user”,
“id”: “901569848744”,
“selfLink”: “https://www.googleapis.com/blogger/v3/users/901569848744",
“blogs”: {
“selfLink”: “https://www.googleapis.com/blogger/v3/users/901569848744/blogs"
}
}
Standard query parameters
The following query parameters can be used with all methods and all resources in the Blogger APIs.

Query parameters that apply to all Blogger APIs operations are shown in the table below.

Notes (on API keys and auth tokens):

The key parameter is required with every request, unless you provide an OAuth 2.0 token with the request.
You must send an authorization token with every request that requires an OAuth scope. OAuth 2.0 is the only supported authorization protocol.
You can provide an OAuth 2.0 token with any request in one of two ways:
Using the access_token query parameter like this: ?access_token=oauth2-token
Using the HTTP Authorization header like this: Authorization: Bearer oauth2-token
All parameters are optional except where noted.

Parameter Meaning Notes
access_token OAuth 2.0 token for the current user.
One possible way to provide an OAuth 2.0 token.
callback Callback function.
Name of the JavaScript callback function that handles the response.
Used in JavaScript JSON-P requests.
fields Selector specifying a subset of fields to include in the response.
For more information, see the partial response section in the Performance Tips document.
Use for better performance.
key API key. (REQUIRED*)
*Required unless you provide an OAuth 2.0 token.
Your API key identifies your project and provides you with API access, quota, and reports.
Obtain your project’s API key from the Google API Console.
prettyPrint
Returns response with indentations and line breaks.

Returns the response in a human-readable format if true.
Default value: true.
When this is false, it can reduce the response payload size, which might lead to better performance in some environments.
quotaUser Alternative to userIp.
Lets you enforce per-user quotas from a server-side application even in cases when the user’s IP address is unknown. This can occur, for example, with applications that run cron jobs on App Engine on a user’s behalf.
You can choose any arbitrary string that uniquely identifies a user, but it is limited to 40 characters.
Overrides userIp if both are provided.
Learn more about Capping API usage.
userIp IP address of the end user for whom the API call is being made.
Lets you enforce per-user quotas when calling the API from a server-side application.
Learn more about Capping API usage.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Blogger JSON API: Performance Tips
This document covers some techniques you can use to improve the performance of your application. In some cases, examples from other APIs or generic APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Blogger APIs.

Using gzip
An easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.

In order to receive a gzip-encoded response you must do two things: Set an Accept-Encoding header, and modify your user agent to contain the string gzip. Here is an example of properly formed HTTP headers for enabling gzip compression:

Accept-Encoding: gzip
User-Agent: my program (gzip)
Working with partial resources
Another way to improve the performance of your API calls is by sending and receiving only the portion of the data that you’re interested in. This lets your application avoid transferring, parsing, and storing unneeded fields, so it can use resources including network, CPU, and memory more efficiently.

There are two types of partial requests:

Partial response: A request where you specify which fields to include in the response (use the fields request parameter).
Patch: An update request where you send only the fields you want to change (use the PATCH HTTP verb).
More details on making partial requests are provided in the following sections.

Partial response
By default, the server sends back the full representation of a resource after processing requests. For better performance, you can ask the server to send only the fields you really need and get a partial response instead.

To request a partial response, use the fields request parameter to specify the fields you want returned. You can use this parameter with any request that returns response data.

Note that the fields parameter only affects the response data; it does not affect the data that you need to send, if any. To reduce the amount of data you send when modifying resources, use a patch request.

Example
The following example shows the use of the fields parameter with a generic (fictional) “Demo” API.

Simple request: This HTTP GET request omits the fields parameter and returns the full resource.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY
Full resource response: The full resource data includes the following fields, along with many others that have been omitted for brevity.

{
“kind”: “demo”,
…
“items”: [
{
“title”: “First title”,
“comment”: “First comment.”,
“characteristics”: {
“length”: “short”,
“accuracy”: “high”,
“followers”: [“Jo”, “Will”],
},
“status”: “active”,
…
},
{
“title”: “Second title”,
“comment”: “Second comment.”,
“characteristics”: {
“length”: “long”,
“accuracy”: “medium”
“followers”: [ ],
},
“status”: “pending”,
…
},
…
]
}
Request for a partial response: The following request for this same resource uses the fields parameter to significantly reduce the amount of data returned.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
Partial response: In response to the request above, the server sends back a response that contains only the kind information along with a pared-down items array that includes only HTML title and length characteristic information in each item.

200 OK

{
“kind”: “demo”,
“items”: [
{
“title”: “First title”,
“characteristics”: {
“length”: “short”
}
},
{
“title”: “Second title”,
“characteristics”: {
“length”: “long”
}
},
…
]
Note that the response is a JSON object that includes only the selected fields and their enclosing parent objects.

Details on how to format the fields parameter is covered next, followed by more details about what exactly gets returned in the response.

Fields parameter syntax summary
The format of the fields request parameter value is loosely based on XPath syntax. The supported syntax is summarized below, and additional examples are provided in the following section.

Use a comma-separated list to select multiple fields.
Use a/b to select a field b that is nested within field a; use a/b/c to select a field c nested within b.
Exception: For API responses that use “data” wrappers, where the response is nested within a data object that looks like data: { … }, do not include “data” in the fields specification. Including the data object with a fields specification like data/a/b causes an error. Instead, just use a fields specification like a/b.

Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses “( )”.
For example: fields=items(id,author/email) returns only the item ID and author’s email for each element in the items array. You can also specify a single sub-field, where fields=items(id) is equivalent to fields=items/id.

Use wildcards in field selections, if needed.
For example: fields=items/pagemap/* selects all objects in a pagemap.

More examples of using the fields parameter
The examples below include descriptions of how the fields parameter value affects the response.

Note: As with all query parameter values, the fields parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.

Identify the fields you want returned, or make field selections.
The fields request parameter value is a comma-separated list of fields, and each field is specified relative to the root of the response. Thus, if you are performing a list operation, the response is a collection, and it generally includes an array of resources. If you are performing an operation that returns a single resource, fields are specified relative to that resource. If the field you select is (or is part of) an array, the server returns the selected portion of all elements in the array.

Here are some collection-level examples:
Examples Effect
items Returns all elements in the items array, including all fields in each element, but no other fields.
etag,items Returns both the etag field and all elements in the items array.
items/title Returns only the title field for all elements in the items array.

Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly.
context/facets/label Returns only the label field for all members of the facets array, which is itself nested under the context object.
items/pagemap/*/title For each element in the items array, returns only the title field (if present) of all objects that are children of pagemap.

Here are some resource-level examples:
Examples Effect
title Returns the title field of the requested resource.
author/uri Returns the uri sub-field of the author object in the requested resource.
links/*/href
Returns the href field of all objects that are children of links.
Request only parts of specific fields using sub-selections.
By default, if your request specifies particular fields, the server returns the objects or array elements in their entirety. You can specify a response that includes only certain sub-fields. You do this using “( )” sub-selection syntax, as in the example below.
Example Effect
items(title,author/uri) Returns only the values of the title and author’s uri for each element in the items array.
Handling partial responses
After a server processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code, along with the requested data. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code, along with an error message telling the user what was wrong with their fields selection (for example, “Invalid field selection a/b”).

Here is the partial response example shown in the introductory section above. The request uses the fields parameter to specify which fields to return.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
The partial response looks like this:

200 OK

{
“kind”: “demo”,
“items”: [
{
“title”: “First title”,
“characteristics”: {
“length”: “short”
}
},
{
“title”: “Second title”,
“characteristics”: {
“length”: “long”
}
},
…
]
Note: For APIs that support query parameters for data pagination (maxResults and nextPageToken, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized.

Patch (partial update)
You can also avoid sending unnecessary data when modifying resources. To send updated data only for the specific fields that you’re changing, use the HTTP PATCH verb. The patch semantics described in this document are different (and simpler) than they were for the older, GData implementation of partial update.

The short example below shows how using patch minimizes the data you need to send to make a small update.

Example
This example shows a simple patch request to update only the title of a generic (fictional) “Demo” API resource. The resource also has a comment, a set of characteristics, status, and many other fields, but this request only sends the title field, since that’s the only field being modified:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
“title”: “New title”
}
Response:

200 OK

{
“title”: “New title”,
“comment”: “First comment.”,
“characteristics”: {
“length”: “short”,
“accuracy”: “high”,
“followers”: [“Jo”, “Will”],
},
“status”: “active”,
…
}
The server returns a 200 OK status code, along with the full representation of the updated resource. Since only the title field was included in the patch request, that’s the only value that is different from before.

Note: If you use the partial response fields parameter in combination with patch, you can increase the efficiency of your update requests even further. A patch request only reduces the size of the request. A partial response reduces the size of the response. So to reduce the amount of data sent in both directions, use a patch request with the fields parameter.

Semantics of a patch request
The body of the patch request includes only the resource fields you want to modify. When you specify a field, you must include any enclosing parent objects, just as the enclosing parents are returned with a partial response. The modified data you send is merged into the data for the parent object, if there is one.

Add: To add a field that doesn’t already exist, specify the new field and its value.
Modify: To change the value of an existing field, specify the field and set it to the new value.
Delete: To delete a field, specify the field and set it to null. For example, “comment”: null. You can also delete an entire object (if it is mutable) by setting it to null. If you are using the Java API Client Library, use Data.NULL_STRING instead; for details, see JSON null.
Note about arrays: Patch requests that contain arrays replace the existing array with the one you provide. You cannot modify, add, or delete items in an array in a piecemeal fashion.

Using patch in a read-modify-write cycle
It can be a useful practice to start by retrieving a partial response with the data you want to modify. This is especially important for resources that use ETags, since you must provide the current ETag value in the If-Match HTTP header in order to update the resource successfully. After you get the data, you can then modify the values you want to change and send the modified partial representation back with a patch request. Here is an example that assumes the Demo resource uses ETags:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
This is the partial response:

200 OK

{
“etag”: “ETagString”
“title”: “New title”
“comment”: “First comment.”,
“characteristics”: {
“length”: “short”,
“level”: “5”,
“followers”: [“Jo”, “Will”],
}
}
The following patch request is based on that response. As shown below, it also uses the fields parameter to limit the data returned in the patch response:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: “ETagString”

{
“etag”: “ETagString”
“title”: “”, /* Clear the value of the title by setting it to the empty string. /
“comment”: null, / Delete the comment by replacing its value with null. /
“characteristics”: {
“length”: “short”,
“level”: “10”, / Modify the level value. /
“followers”: [“Jo”, “Liz”], / Replace the followers array to delete Will and add Liz. /
“accuracy”: “high” / Add a new characteristic. */
},
}
The server responds with a 200 OK HTTP status code, and the partial representation of the updated resource:

200 OK

{
“etag”: “newETagString”
“title”: “”, /* Title is cleared; deleted comment field is missing. /
“characteristics”: {
“length”: “short”,
“level”: “10”, / Value is updated./
“followers”: [“Jo” “Liz”], / New follower Liz is present; deleted Will is missing. /
“accuracy”: “high” / New characteristic is present. */
}
}
Constructing a patch request directly
For some patch requests, you need to base them on the data you previously retrieved. For example, if you want to add an item to an array and don’t want to lose any of the existing array elements, you must get the existing data first. Similarly, if an API uses ETags, you need to send the previous ETag value with your request in order to update the resource successfully.

Note: You can use an “If-Match: *” HTTP header to force a patch to go through when ETags are in use. If you do this, you don’t need to do the read before the write.

For other situations, however, you can construct the patch request directly, without first retrieving the existing data. For example, you can easily set up a patch request that updates a field to a new value or adds a new field. Here is an example:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
“comment”: “A new comment”,
“characteristics”: {
“volume”: “loud”,
“accuracy”: null
}
}
With this request, if the comment field has an existing value, the new value overwrites it; otherwise it is set to the new value. Similarly, if there was a volume characteristic, its value is overwritten; if not, it is created. The accuracy field, if set, is removed.

Handling the response to a patch
After processing a valid patch request, the API returns a 200 OK HTTP response code along with the complete representation of the modified resource. If ETags are used by the API, the server updates ETag values when it successfully processes a patch request, just as it does with PUT.

The patch request returns the entire resource representation unless you use the fields parameter to reduce the amount of data it returns.

If a patch request results in a new resource state that is syntactically or semantically invalid, the server returns a 400 Bad Request or 422 Unprocessable Entity HTTP status code, and the resource state remains unchanged. For example, if you attempt to delete the value for a required field, the server returns an error.

Alternate notation when PATCH HTTP verb is not supported
If your firewall does not allow HTTP PATCH requests, then do an HTTP POST request and set the override header to PATCH, as shown below:

POST https://www.googleapis.com/…
X-HTTP-Method-Override: PATCH
…
Difference between patch and update
In practice, when you send data for an update request that uses the HTTP PUT verb, you only need to send those fields which are either required or optional; if you send values for fields that are set by the server, they are ignored. Although this might seem like another way to do a partial update, this approach has some limitations. With updates that use the HTTP PUT verb, the request fails if you don’t supply required parameters, and it clears previously set data if you don’t supply optional parameters.

It’s much safer to use patch for this reason. You only supply data for the fields you want to change; fields that you omit are not cleared. The only exception to this rule occurs with repeating elements or arrays: If you omit all of them, they stay just as they are; if you provide any of them, the whole set is replaced with the set that you provide.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.