Google Apps Calendar Resource API Developer's Guide: Protocol

The Google Apps Calendar Resource API allows Google Apps administrators to retrieve and manage the Google Calendar resources of their domains in the form of Google Data API feeds.

You can add resources that users in your domain will be able to schedule on their calendars, such as conference rooms, projectors, or company vehicles.

The Calendar Resource API supports the Google Data API protocol. The Google Data API conforms to the Atom Publishing Protocol (AtomPub) publishing and editing model. The AtomPub HTTP requests use the Representational Set Transfer (RESTful) design approach to web services. For more information, see the Google Data APIs Overview.

Contents

Audience

This document is intended for programmers who want to write client applications that can modify and retrieve information about their domain's Google Calendar resources. It provides examples of the basic Calendar Resource API interactions using raw XML and HTTP.

This document assumes that you understand the general ideas behind the Google Data API protocol, and that you are familiar with administering Google Calendar resources. For more information about creating a calendar resource in the control panel, see Scheduling calendar resources.

Getting started

Creating an account

The Calendar Resource API is enabled for the Google Apps Premier and Education Editions. You may want to sign up for a Premier Edition account for testing purposes. For more information about which APIs are enabled for each Google Apps product edition, see the Google Apps APIs Getting Started.

Developing a naming strategy for your calendar resources

When you are creating and updating a calendar resource, you need a flexible naming strategy for your resource names, descriptions, and categories. Descriptive resource information helps users schedule the resource, and helps calendar administrators manage resources over time. We have assembled a few suggestions to consider when building your resources:

• Resource ID — This resource ID is used in every API request. If the resource is created within the control panel, this ID is a series of random numbers. But, when created within the API, you can use your own naming convention to create an ID name that is easier to reference and use. These names are subject to the same rules as any Google Apps user name:
  • The maximum length is 64 characters. The minimum length is 1 character.
  • The resourceId name can not begin with a dot. Nor can the name have more than one consecutive dot. An example of an incorrect resourceId is .CR..NYC .
  • The legal characters include: 'a'through 'z', 'A' through 'Z', '0' through '9', '.', '-', '_' .

  A suggested naming pattern is:

  • [resource type]-[city]-[building]-[floor or location]-[name]-[optional information]

    CR-NYC-14-12-BR

    This conference room is in New York city, building 14, floor 12, room initials BR (Boardroom).

    CAM-PARIS-L-CAMCORD-HD-2

    This is the camera in your Paris office building's lobby. It is the high definition camcorder, specifically camera number 2.

• Resource common name — In the calendar user interface, the common name is the name seen by the user when selecting from a calendar's resource list. The common name has to be easy to find, give enough information for a decision, but remain short and concise in the list. Use consistent naming and punctuation when organizing these resources so that the resources can be managed and physically located. A resource common name is limited to 100 characters. Note, the above resource IDs are in capital letters, and the resource common names are mixed-case.

  Since conference rooms are the most common resource, this example includes a special conference room recommendation which groups your conference room listings together.

  The suggested pattern for a conference room is:

  • [city]-[building]-[floor or location]-[optional, resource specific information]

    NYC-14-12-Boardroom-15-VC

    This conference room is in New York city in building 14, on floor 12. The room's name is Boardroom which holds 15 people and has video conferencing equipment.

  The suggested pattern for a general resource type is:

  • (resource type)-[city]-[building]-[floor or location]-[optional, resource specific information]

    (Guest Office)-Tokyo-44-2-245C

    This guest office in Tokyo is in building 44 on the second floor. It is office number 245, and, of all of the desks in this office, this guest is specifically reserving desk 'C'.

    (Bike)-London-43-Lobby-Bike-1

    This bicycle is in London at building 43's lobby. This is 'Bike 1' (rather than 'Bike 2' or 'Bike 3').

    (Vehicle)-LA-Chrevrolet-Main-North-4

    This vehicle is in Los Angeles. It is a Chrevrolet parked at the Main building in the North parking lot in parking space 4.

    (Camera)-Paris-Lobby-Camcorder-HD-2+tripod+batteries

    This camera is kept in the Paris office's lobby. It is the high definition camcorder, camera number '2'. It includes a tripod and batteries.

• Resource description — This summary answers the question, "What additional information do I need other than this resource's name, and where it is located?" For example: contact information or special instructions. A resource description is limited to 1,000 characters.
• Resource type — A resource type is found by asking the question, "What are my resource categories?" For example: conference rooms, guest offices, phone rooms, bikes, vehicles, cameras, projectors, shared servers, basketball courts, bulldozers, etc. The resource type name is limited to 100 characters.

Back to top

Authenticating to the Calendar Resource service

Access to the Calendar Resource API is limited to domain administrators who have authenticate each request. The Calendar Resource API feed is private, and unauthenticated requests are not accepted. Before retrieving or changing calendar resource properties, your client must authenticate using the ClientLogin authentication system. To use this system, you submit the email address and password of the domain administrator making the request. The authentication service returns an authentication token that your client can then send to the Calendar Resource API service along with every subsequent request.

For more information about authentication with Google Data APIs in general, see the authentication documentation.

The samples in this document assume you are providing the appropriate authentication.

ClientLogin user name and password authentication

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 request contains the following Content-type header:

Content-type: application/x-www-form-urlencoded

The POST body contains a set of query parameters that look like parameters passed by an HTML form. These are:

accountType

The type of account to be authenticated. To support Google Apps users, use the HOSTED_OR_GOOGLE account type. This type is authenticated first as a hosted account. If this attempt fails, the administrator or user is authenticated as a Google account. This allows for the primary and secondary administrators to log in to this account.

Email

The administrator's or user's email address

Passwd

The administrator's or user's password. If using XML outside of a client library, the email address and password value must be URL-encoded. For example, the URL-encoding for admin@example.com is admin%40example.com

service

The Calendar Resource ClientLogin service name is apps, a Google Apps service. For other service names, see the service name list.

source

Identifies your client application for support purposes. This string should take the form of your companyName-applicationName-versionID.

The POST body contains the following string with each parameter's name-value pair:

POST &Email=yourAdminEmail&Passwd=yourAdminPassword&accountType=HOSTED_OR_GOOGLE&service=apps
&source=companyName-applicationName-versionID

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

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

If the request 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 SID is the session ID valid for the life of the session. The Auth value is the authorization token that you'll send to the Calendar Resource service with each of your subsequent API requests. Google recommends keeping the authorization token in memory rather than writing it to a file. In the context of this guide, you can ignore the SID and LSID values.

Since all requests to the Calendar Resource service require authentication, set the Content-type and Authorization headers in all service requests using the following format:

Content-type: application/atom+xml
Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned from the ClientLogin POST request. Use this token for all requests in a given session. A new token is not required for each Calendar Resource request.

Note: Tokens are valid for 24 hours. If an authenticated request fails, it may mean you need to acquire another token by posting the administrator's or user's credentials to the ClientLogin URL again.

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

If you get a CAPTCHA error with your request, the error response will return a CAPTCHA token and URL:

CaptchaToken=captchaToken
CaptchaUrl=Captcha?ctoken=captchaToken
Error=cr
Url=https://www.google.com/a/example.com/ErrorMsg?Email=adminLogin
%40yourDomainName&service=apps&id=cr&timeStmp=1222898074&secTok=theCAPTCHAtoken 

For information about handling a CAPTCHA challenge, see the CAPTCHA FAQ.

Back to top

Creating a new calendar resource

To create a calendar resource, use the following POST request:

POST https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain

The following XML shows a sample request to create a new calendar resource, the Boardroom conference room in NYC:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
    <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
    <apps:property name='resourceCommonName' value='Boardroom'/>
    <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
    <apps:property name='resourceType' value='CR'/>
</atom:entry>

Note: When working with the API, the maximum number of calendar resources per domain is 3,000.

The properties are:

resourceId

This is a required property. The maximum length is 64 characters. The resource ID is a unique name you give this resource. We recommend standardizing on a naming strategy that makes it easy to remember this resource ID. For naming suggestions and additional naming rules, see Developing a naming strategy for your calendar resources.

Note: When a resource is created in the control panel, the resource ID is a series of numbers.

resourceCommonName

The common name is the resource name seen by users in a calendar's resource list. This is an optional property when creating a resource, but is strongly recommended. This name has a maximum of 100 characters. For naming suggestions, see Developing a naming strategy for your calendar resources.

resourceDescription

The description is a brief summary of this resource shown in the control panel. This is an optional property, but is strongly recommended. The description is limited to a maximum of 1,000 characters.

resourceType

The type is a general category common to several resources. This is an optional property, but is strongly recommended. The type name has a maximum of 100 characters.

When using our suggested naming strategy, a resource type becomes very helpful to the user. Resource hierarchies are automatically created when three of more resources are added with the same first three characters in their common name. In the calendar resource list, these hierarchies occur when the calendar resource list begins to scroll and the immediate screen is full with several resources.

A successful response returns an HTTP 201 status code found in the Google Data API status codes documentation. Along with the status code, the response returns an AtomPub feed with the entry element showing new resource's settings:

<entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schema.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR</id>
    <updated>2008-10-17T15:02:45.646Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/id'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/id'/>
    <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
    <apps:property name='resourceCommonName' value='Boardroom'/>
    <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
    <apps:property name='resourceType' value='CR'/>
</entry>

Back to top

Retrieving calendar resources

Retrieving a single calendar resource

To retrieve a single calendar's resource, send the following HTTP GET request to the resource ID's feed URL. Include the Authorization header as described in Authenticating.

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resourceId

This operation has no parameters in the request body.

A successful response returns an HTTP 200 status code from the Google Data API status codes:

<entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR</id>
    <updated>2008-10-17T15:19:46.467Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR'/>
    <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
    <apps:property name='resourceCommonName' value='Boardroom'/>
    <apps:property name='resourceEmail' value='domain_123456@resource.calendar.google.com'/>
    <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
    <apps:property name='resourceType' value='CR'/>
</entry>

The response entry element returns the same properties used when creating a resource along with the calendar's encoded resourceEmail property:

resourceEmail

The resource email address is the public address used to view and reserve this resource in a calendar. The system's naming convention for resourceEmail is <domain name>_nnn...@resource.calendar.google.com. This is the ID in a calendar's Calendar Details page's Calendar Address section. Your calendar must be public for others to use this calendar address.

Retrieving all calendar resources

The API's XML feed uses pagination for results listing more than 100 calendar resources. For a large response, each page of results returns a maximum of 100 entries, and includes a URI in a <link rel='next'...> tag pointing to the next page of results. When developing your client application, your code needs to manage these additional results.

To retrieve the first page of resource entries associated with a particular calendar, send an HTTP GET request ending with a forward slash to a resource feed URL. Include the Authorization header as described in Authenticating.

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/

Optionally, you can send an HTTP GET request with an empty string in the start parameter to a resource feed URL.

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/?start=""

This operation has no parameters in the request body.

A successful response returns an HTTP 200 status code from the Google Data API status codes.

In this example, the response entry elements return the properties for two resources:

<feed xmlns:atom='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:apps='http://schemas.google.com/apps/2006'>
   <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain</id>
   <updated>2008-10-17T15:29:21.064Z</atom:updated>
   <link rel='next' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/?start=the next resourceId'/>
   <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain'/>
   <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain'/>
   <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain?start=CR-NYC-14-12-BR'/>
   <openSearch:startIndex>1</openSearch:startIndex>
   <entry>
      <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR</id>
      <updated>2008-10-17T15:29:21.064Z</updated>
      <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR'/>
      <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/feeds/calendar/resource/2.0/your domain/CR-NYC-14-12-BR'/>
      <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
      <apps:property name='resourceCommonName' value='Boardroom'/>
      <apps:property name='resourceEmail' value='domain_123456@resource.calendar.google.com'/>
      <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
      <apps:property name='resourceType' value='CR'/>
   </entry>
   <entry>
        <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/?start=(Bike)-London-43-Lobby-Bike-1</id>
        <updated>2008-10-17T15:29:21.064Z</updated>
        <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/(Bike)-London-43-Lobby-Bike-1'/>
        <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/(Bike)-London-43-Lobby-Bike-1'/>
        <apps:property name='resourceId' value='(Bike)-London-43-Lobby-Bike-1'/>
        <apps:property name='resourceCommonName' value='London bike-1'/>
        <apps:property name='resourceEmail' value='domain_123457@resource.calendar.google.com'/>
        <apps:property name='resourceDescription' value='Bike is in London at building 43's lobby.'/>
        <apps:property name='resourceType' value='(Bike)'/>
    </entry>
</feed>

If the domain has over 100 resources, the response includes a next URI of the next page of results:

<link rel="next" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/calendar/resource/2.0/domainName/?start=the next page's first resourceId>

To retrieve these additional pages, use the next URI in your subsequent GET requests to retrieve all of your calendar resources:

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/domainName/?start=the next page's first resourceId

Back to top

Updating a calendar resource

To update a calendar resource, send a PUT request to a resource ID's feed URL. Include the Authorization header as described in Authenticating.

PUT https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resourceId

You can update the resourceCommonName, resourceDescription, and resourceType properties:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceCommonName' value='new common name'/>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceDescription' value='new description'/>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceType' value='new type'/>
</atom:entry>

A successful response returns an HTTP 200 status code from the Google Data API status codes.

The response entry element returns these resource settings:

<entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resourceId</id>
    <updated>2008-10-17T15:21:22.223Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resouceId'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resourceId'/>
    <apps:property name='resourceCommonName' value='new common name'/>
    <apps:property name='resourceDescription' value='new description'/>
    <apps:property name='resourceType' value='new type'/>
</entry>

Back to top

Deleting a calendar resource

To delete a calendar resource, send a DELETE request to a resource ID's feed URL. Include the Authorization header as described in Authenticating.

DELETE https://apps-apis.google.com/a/feeds/calendar/resource/2.0/your domain/resourceId

A successful response returns an HTTP 200 status code from the Google Data API status codes. The XML body of a successful response to a DELETE request is empty.

Back to top