Несколько общих моментов по работе с Google API.

Как Вы уже могли неоднократно замечать я в последнее время активно интересуюсь работой с Google API в самых различных его проявлениях — от простой авторизации в сервисах до работы с API конкретных продуктов. Соответственно накопилось достаточно материала для того, чтобы сделать какие-либо общие выводы по работе в целом, указать на моменты, которые следует учитывать при разработках и т.д.
Несмотря на то, что Google сам предоставляет разработчикам массу документации по работе с API, думаю, что кратко изложенный обобщенный материал по работе с Google будет не лишним, особенно тем, кто не любит часами перелопачивать мегабайты информации.

Итак, что касается общих моментов по работе с Google API.
Во-первых, абсолютно любой API продукта Google, использовать который можно не одинаково эффективно как в настольных приложениях так и в Сети, базируется на Google Data Protocol. Например, тот же API Контактов или Календаря возвращают данные сформированные по всем правилам GData, а Google Chart API, рассчитанный на работу именно в Сети, GData не использует. В результате можно выделить следующие составные элементы любого XML-документа, который Вы будете получать в ответ от сервера:
1. Feed — здесь все дочерние узлы будут содержать общую информацию по запрашиваемому документу (название, имя генератора, даты создания и последнего изменения документа и т.д.). А также очень важную информацию в узлах Link о которых речь пойдет немного позже.
2. Entry — содержание этих узлов зависят от того, API какого сервиса вы используете. Что логично. Но в entry также помимо специфичной информации могут включаться узлы GData. Например, вот узел entry одного из контактов в моей адресной книге:

<entry gd:etag="QHVSLyt7ImA9WxBVEksKTww.">
<id>http://www.google.com/m8/feeds/contacts/myadressses%40gmail.com/base/19628288c96f706</id>
<updated>2010-02-15T19:08:01.990Z</updated>
<app:edited  xmlns:app="http://www.w3.org/2007/app">2010-02-15T19:08:01.990Z</app:edited>
<category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#contact" />
<title />
<link rel="http://schemas.google.com/contacts/2008/rel#photo" type="image/*"  href="http://www.google.com/m8/feeds/photos/media/myadressses%40gmail.com/19628288c96f706" />
<link rel="self"  type="application/atom+xml" href="http://www.google.com/m8/feeds/contacts/myadressses%40gmail.com/full/19628288c96f706" />
<link rel="edit"  type="application/atom+xml" href="http://www.google.com/m8/feeds/contacts/myadressses%40gmail.com/full/19628288c96f706" />
<gd:email rel="http://schemas.google.com/g/2005#other" address="email@email.com"  primary="true" />
</entry>

Этот узел прекрасный образец того, что Вы можете НЕ найти при обработке XML-документа, т.к. несмотря на то, что запрос отправлялся к Google Contacts API узел entry не содержит ни одного узла, относящегося конкретно к API контактов — только общие сведения и узел gd:email из GData. Отсюда следует один простой вывод: прежде, чем начинать работу с API какого-либо сервиса Google необходимо иметь под рукой библиотеку или просто набор функций и процедур для обработки всего, что относится к GData. Разработчики Google поступили абсолютно правильно и логично — зачем отправлять одни и те же данные в разных узлах? Есть основа — GData, в GData выделен ряд узлов, каждый из которых несет определенную информацию (email, имя пользователя и т.д. всего порядка 50 узлов). Эта информация часто используется в различных сервисах и включается в entry любого документа абсолютно одинаково. Если же нужна специфика, например, отдать пользователю данные по мероприятию в Календаре — то здесь уже свои пространства имен, свои узлы (gcal:…).
3. Link. Эти узлы, как понятно из названия, содержат ссылки на что-либо. Какие именно — зависит от содержимого в атрибуте rel и type. Например:

<link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/>

содержит ссылку на feed в формате xml, а узел:

<link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>

Содержит адрес на который необходимо отправлять запрос PUT или DELETE для соответственно редактирования или удаления записи.
И при обработке любого документа обязательно следует обращать внимание на узлы link. Всё дело в том, что сервер может вернуть вам не всю информацию, а только часть. Например, если вы без дополнительных параметров запросите сведения о своих контактах, то сервер вернет только первые 25 записей, адрес для доступа к следующим 25 контактам будет содержаться у узле link с атрибутом next. Поиск адреса для доступа к следующей «порции» данных можно осуществить, например так:

function GetNextLink(aXMLDoc: TNativeXml): string;
var i:integer;
     List: TXmlNodeList;
begin
 Result:='';
 List:=TXmlNodeList.Create;
 aXMLDoc.Root.NodesByName('link',List);
 for i:=0 to List.Count-1 do
   begin
     if List.Items[i].ReadAttributeString('rel')='next' then
       begin
         Result:=List.Items[i].ReadAttributeString('href');
         break;
       end;
   end;
end;

Если функция вернет пустую строку, то это будет означать, что получены все имеющиеся данные. Соответственно для доступа к предыдущим результатам запроса используется узел link с атрибутом rel=previous. Узлы link с атрибутами next и previous всегда содержатся в feed.
Ещё одним «тонким» моментом при работе с API являются узлы и атрибуты ETag. Здесь следует отметить следующее: если Ваша цель работы с API только чтение данных, то на etag можно и не обращать внимание, но если в планах есть также и редактирование данных на сервере, то получение информации по etag для узлов entry просто необходима, так как содержимое этих атрибутов является идентификатором при редактировании любых данных. Также необходимо помнить, что etag обычно содержит кавычки — кавычки эти тоже необходимо отправлять на сервер. Например, такой etag:
gd:etag=»W/»AkYFSXYzfyt7ImA9WxBaGUQ.»»
Должен передаваться в запросах как строка:
W/»AkYFSXYzfyt7ImA9WxBaGUQ.»
Если убрать кавычки — сервер вернет ошибку.
Что касается редактирования графической информации, например, загрузки фотографий и т.д., то адрес для загрузки фото опять же следует искать в узлах link, содержащих атрибуты rel=»http://schemas.google.com/…/2008/rel#photo» type=»image/*». Загружаются изображения как обычно — запросами POST, реже — PUT.