Deprecated

The Issue Tracker Data API has been deprecated and will be shut down on June 14, 2013

See http://googleblog.blogspot.com/2012/12/winter-cleaning.html

The Issue Tracker Data API allows client applications to view and update issues on Project Hosting on Google Code in the form of Google Data API feeds. Your client application can use the Issue Tracker Data API to create new issues & issue comments, request a list of issues, request issue comments for an issue, edit existing issues, and query for issues that match a particular criteria.

In addition to providing some background on the capabilities of the Issue Tracker Data API, this document provides examples of basic Data API interactions using raw XML and HTTP.

• Deprecated
• Audience
• Authentication
• Authenticating AuthSub proxy
• Authenticating ClientLogin username/password
• Retrieving a list of issues
• Retrieving all issues
• Retrieving issues using query parameters
• Retrieving issues comments for an issue
• Creating issues
• Modifying an issue or creating issue comments
• Deleting issues/issue comments

Audience

This document is intended for programmers who want to write client applications that can interact with Project Hosting on Google Code using XML and HTTP. This document assumes that you understand the general ideas behind the Google Data APIs protocol, and that you're familiar with the Issue Tracker GUI.

If you're using a UNIX system and want to try the examples in this document without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

For Issue Tracker reference information, see the Protocol reference guide.

Authentication

The following sections describe how to authenticate with Project Hosting on Google Code. Please note that you do NOT need to authenticate if you want to access issues anonymously. You will, however, have to authenticate if you wish to see issues that have permissions set on them or if you wish to create/update issues.

Authenticating AuthSub proxy

AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Project Hosting on Google Code user. Instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf. For more detailed information, see the AuthSub documentation.

When a user first visits your application, they have not yet been authenticated. In this case, you need to display some information indicating to the user that they are not authenticated and a link directing the user to a Google page to authenticate your request for access to their Issue Tracker.

The following query parameters are included in the AuthSubRequest URL:

The AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=https%3A%2F%2Fcode.google.com%2Ffeeds%2Fissues%2F&session=1&secure=0& 

The user follows the link to Google's site and authenticates to their Google Account.

After the user authenticates, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

https://www.example.com/welcome.html?token=yourAuthToken

This token value represents a single-use AuthSub token. In this example, because session=1 was specified, this token can be exchanged for an AuthSub session token by calling the AuthSubSessionToken service with the single-use token in an Authorization header, as follows:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

The AuthSubSessionToken service response includes a Token header that contains the session token and an Expiration header that indicates how long the token will remain valid.

Your application can then use the session token value in the Authorization header of subsequent interactions with your issue tracker.

Here's an example of an HTTP request, containing a non-secure token, that you might send to the Issue Tracker:

GET /feeds/issues/p/PROJECT_NAME/issues/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: code.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Authenticating ClientLogin username/password

Use ClientLogin authentication if your client is a standalone, single-user "installed" client (such as a desktop application). To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters that look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type. These parameters are:

For more information about the parameters, see the Authentication for Installed Applications document.

If the authentication request fails, then the server returns an HTTP 403 Forbidden status code.

If it succeeds, then the server returns an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send to Project Hosting on Google Code with each of your subsequent issues, issue comments-feed requests, so keep a copy of that value. You can ignore the SID and LSID values.

Because all requests to private feeds require authentication, you need to set the Authorization header in all subsequent interactions with Project Hosting on Google Code, using the following format:

Authorization: GoogleLogin auth=<b>yourAuthToken</b>

Where yourAuthToken is the Auth string returned by the ClientLogin request.

For more information about ClientLogin authentication, including sample requests and responses, see Authentication for Installed Applications.

Note: Use the same token for all requests in a given session; don't acquire a new token for each Project Hosting on Google Code request.

Retrieving a list of issues

Retrieving all issues

The Issue Tracker Data API provides a feed that lists the issues for a particular project.

To access this feed and retrieve a list of issues send an HTTP GET to the following URL (be sure to replace PROJECT_NAME with the name of the project that you would like to get issues for):

https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/full

An entry in the issues might look like this:

<entry>
  <id>https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/full/3</id>
  <published>2009-09-08T21:04:31.232Z</published>
  <updated>2009-09-09T20:34:35.365Z</updated>
  <title>This is updated issue summary</title>
  <content type='html'>This is issue description</content>
  <link rel='self' type='application/atom+xml' href='https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/full/3'/>
  <author>
    <name>elizabeth.bennet</name>
    <uri>/u/elizabeth.bennet/</uri>
  </author>
  <issues:cc>
    <issues:uri>/u/@UBhTQl1UARRAVga7/</issues:uri>
    <issues:username>[email protected]</issues:username>
  </issues:cc>
  <issues:cc>
    <issues:uri>/u/fitzwilliam.darcy/</issues:uri>
    <issues:username>fitzwilliam.darcy</issues:username>
  </issues:cc>
  <issues:label>Type-Enhancement</issues:label>
  <issues:label>Priority-Low</issues:label>
  <issues:owner>
    <issues:uri>/u/charlotte.lucas/</issues:uri>
    <issues:username>charlotte.lucas</issues:username>
  </issues:owner>
  <issues:stars>0</issues:stars>
  <issues:state>open</issues:state>
  <issues:status>Started</issues:status>
</entry>

For information about what each of those elements means, see the Issue Tracker Data API reference guide, Google Data APIs Protocol Reference document, or the Atom 1.0 specification.

If your request fails for some reason, Issue Tracker Data API may return a different status code. More information about HTTP status codes is also available in the Google Data APIs Protocol Reference document.

Retrieving issues using query parameters

The Issue Tracker Data API lets you request a set of issues that match specified criteria, such as requesting issues created or updated in a given date range.

For example to send a date-range query:

1. First, add the updated-min and updated-max parameters to the request URL. To get all the issue entries updated from March 16, 2008 to March 24, 2008, send an HTTP request to the issue's feed URL: GET https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/full?updated-min=2008-03-16T00:00:00&updated-max=2009-03-24T23:59:59
2. After you send the GET request, Issue Tracker Data API may return a redirect, depending on various factors. If so, send another GET request to the redirect URL.
3. When you send that GET request, Issue Tracker Data API returns an HTTP 200 OK status code and a feed containing any items that were created or updated in the date range you specified.

The Issue Tracker Data API supports the following query parameters:

For more information about query parameters, see the Issue Tracker Data API Reference Guide and the Google Data APIs Reference Guide.

Retrieving issues comments for an issue

For an issue, the Issue Tracker Data API provides a feed that lists the comments for that particular issue.

To access this feed and retrieve the list of issue comments send an HTTP GET to the following URL (be sure to replace PROJECT_NAME with the name of the project and replace ISSUE_ID with the issue id for the issue that you want to get issue comments for):

https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/3/comments/full

An entry in the issue comments might look like this:

<entry>
  <id>https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/13/comments/full/1</id>
  <published>2009-09-09T20:30:17.836Z</published>
  <updated>2009-09-09T20:30:17.836Z</updated>
  <title>Comment 1 by elizabeth.bennet</title>
  <content type='html'>ISSUE CONTENT</content>
  <link rel='self' type='application/atom+xml' href='https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/3/comments/full/1'/>
  <author>
    <name>elizabeth.bennet</name>
    <uri>/u/elizabeth.bennet/</uri>
  </author>
  <issues:updates>
    <issues:ccUpdate>-fitzwilliam.darcy</issues:ccUpdate>
    <issues:ccUpdate>[email protected]</issues:ccUpdate>
    <issues:label>-Type-Defect</issues:label>
    <issues:label>-Milestone-2009</issues:label>
    <issues:label>-Priority-Medium</issues:label>
    <issues:label>Type-Enhancement</issues:label>
    <issues:label>Priority-Low</issues:label>
    <issues:ownerUpdate>charlotte.lucas</issues:ownerUpdate>
    <issues:status>Started</issues:status>
    <issues:summary>This is updated issue summary</issues:summary>
  </issues:updates>
</entry>

For information about what each of those elements means, see the Issue Tracker Data API reference guide, Google Data APIs Protocol Reference document, or the Atom 1.0 specification.

If your request fails for some reason, the Issue Tracker Data API may return a different status code. More information about HTTP status codes is also available in the Google Data APIs Protocol Reference document.

Creating issues

After authenticating, you can publish new Issue Tracker entries.

First, create an XML representation of the issue to publish. This XML needs to be in the form of an Atom <entry> element, which might look like this:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:issues='http://schemas.google.com/projecthosting/issues/2009'>
  <title>This is issue summary - create issue</title>
  <content type='html'>This is issue description</content>
  <author>
    <name>elizabeth.bennet</name>
  </author>
  <issues:status>Accepted</issues:status>
  <issues:owner>
    <issues:username>elizabeth.bennet</issues:username>
  </issues:owner>
  <issues:label>Type-Defect</issues:label>
  <issues:label>Milestone-2009</issues:label>
  <issues:label>Priority-Medium</issues:label>
  <issues:cc>
    <issues:username>fitzwilliam.darcy</issues:username>
  </issues:cc>
  <issues:cc>
    <issues:username>[email protected]</issues:username>
  </issues:cc>
</entry>

To publish this entry, send it to the Issue Tracker's post URL as follows:

1. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type.
2. Then find the Issue Tracker's post URL in the Issues feed by locating the <link> element where the rel attribute ends with #post. The Issue Tracker's post URL is given as the href attribute of this element, which is in this format: https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/full
3. Project Hosting on Google Code creates an issue using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new issue in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by the Issue Tracker Data API, such as an <id> element. This operation WILL FAIL unless you change owner/cc fields to those added as owner/members for the specified project. Required elements: title, content, author.
4. If your request fails for some reason, the Issue Tracker Data API may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

Modifying an issue or creating issue comments

After authenticating, you can modify an issue by creating new issue comments.

First, create an XML representation of the issue comment to publish. This XML needs to be in the form of an Atom <entry> element, which might look like this:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:issues='http://schemas.google.com/projecthosting/issues/2009'>
  <content type='html'>This is comment - update issue</content>
  <author>
    <name>elizabeth.bennet</name>
  </author>
  <issues:updates>
    <issues:summary>This is updated issue summary</issues:summary>
    <issues:status>Started</issues:status>
    <issues:ownerUpdate>charlotte.lucas</issues:ownerUpdate>
    <issues:label>-Type-Defect</issues:label>
    <issues:label>Type-Enhancement</issues:label>
    <issues:label>-Milestone-2009</issues:label>
    <issues:label>-Priority-Medium</issues:label>
    <issues:label>Priority-Low</issues:label>
    <issues:ccUpdate>-fitzwilliam.darcy</issues:ccUpdate>
    <issues:ccUpdate>[email protected]</issues:ccUpdate>
  </issues:updates>
</entry>

To publish this entry, send it to the Issue Tracker's post URL as follows:

1. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type.
2. Then find the Issue Tracker's post URL in the metafeed by locating the <link> element where the rel attribute ends with #post. The issue's post URL is given as the href attribute of this element, which is in this format https://code.google.com/feeds/issues/p/PROJECT_NAME/issues/ISSUE_ID/comments/full
3. Project Hosting on Google Code creates a issue using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new issue in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by the Issue Tracker Data API, such as an <id> element. Required elements: author.
4. If your request fails for some reason, the Issue Tracker Data API may return a different status code. For information about the status codes, see the Google Data API protocol reference document.

Deleting issues/issue comments

Deleting an issue should be rarely done and is only supported through the UI. Instead close the issue instead by setting the appropriate issue status by adding an issue comment as described above.