Постраничная выдача коллекций

Коллекции возвращаются постранично. Страницы представляют собой документы Atom Feed, связанные между собой ссылками на следующий документ ("обратная" связь не поддерживается). На каждой странице может быть не более ста элементов.

Ссылка на следующую страницу коллекции в общем виде:

<link rel="next" href="{адрес коллекции}/{порядок выдачи};{смещение страницы}/[?limit={значение}]" />

Пример:

<link rel="next" href="http://api-fotki.yandex.ru/api/users/alekna/album/63988/photos/updated;2009-01-27T11:57:19Z,126744/" />

Параметры адреса:

Обязательный:

• {порядок выдачи} - порядок отображения элементов выдачи. Допустимые значения:

  updated (по умолчанию) - по времени последнего изменения, от новых к старым;

  rupdated - по времени последнего изменения, от старых к новым;

  published - по времени загрузки (для фотографии) или создания (для альбома), от новых к старым;

  rpublished - по времени загрузки (для фотографии) или создания (для альбома), от старых к новым;

  created - по времени создания согласно EXIF-данным, от новых к старым (только для фотографий);

  rcreated - по времени создания согласно EXIF-данным, от старых к новым (только для фотографий).

Опциональные:

• {смещение страницы} - смещение страницы в последовательности, заданной {порядком выдачи}. Имеет вид {время},{id}.
  • {время} (обязательный) - время создания ресурса в формате UTC с точностью до секунды.

    Исключение: ссылки с {порядком выдачи} равным created или rcreated, в которых время указывается без часового пояса.

    

    Точность времени относительно мала, поэтому в коллекции могут появляться элементы с одинаковым временем создания. Для различения таких элементов можно использовать опциональный числовой идентификатор id.
  • {id} (опциональный) - числовой идентификатор ресурса на Яндекс.Фотках.
    

    Если при постраничной выдаче коллекции указывать только параметр {время}, то на границах страниц могут появиться дубликаты. Аналогичный эффект может возникнуть, если коллекция изменяется извне непосредственно во время постраничной выдачи. Чтобы избежать этого, нужно при одинаковом значении атрибута atom:id выбирать экземпляр с наиболее свежим atom:updated.

• limit - количество элементов на странице выдачи. Значение — целое число не более 100.

GET /api/users/alekna/album/63988/photos/ HTTP/1.1
Host: api-fotki.yandex.ru
Content-Type: application/atom+xml; charset=utf-8; type=feed

HTTP/1.1 200 OK
Content-Type: application/atom+xml; charset=utf-8; type=feed
Content-Location: http://fotki.yandex.ru/users/alekna/album/63988/
 
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns:f="yandex:fotki">
  <id>urn:yandex:fotki:alekna:album:63988:photos</id>
  <author>
    <name>alekna</name>
  </author>
  <title>Каникулы в Германии</title>
  <updated>2009-01-27T11:57:33Z</updated>
  <summary>Наша школьная поездка в Германию</summary>
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/63988/photos/" rel="self" />
  <link href="http://fotki.yandex.ru/users/alekna/album/63988/" rel="alternate" />
  <f:image-count value="10" />
  <!-- Данная ссылка содержит адрес следующей страницы выдачи: -->
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/63988/photos/updated;2009-01-27T11:57:19Z,126744/" rel="next" />
  <entry>...</entry>
  <entry>...</entry>
  ...
  <entry>...</entry>
</feed>

GET /api/users/alekna/album/63988/photos/updated;2009-01-27T11:57:19Z,126744/ HTTP/1.1
Host: api-fotki.yandex.ru
Content-Type: application/atom+xml; charset=utf-8; type=feed

HTTP/1.1 200 OK
Content-Type: application/atom+xml; charset=utf-8; type=feed
Content-Location: http://fotki.yandex.ru/users/alekna/album/63988/
 
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns:f="yandex:fotki">
  <id>urn:yandex:fotki:alekna:album:63988:photos</id>
  <author>
    <name>alekna</name>
  </author>
  <title>Каникулы в Германии</title>
  <updated>2009-01-27T11:57:33Z</updated>
  <summary>Наша школьная поездка в Германию</summary>
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/63988/photos/" rel="self" />
  <link href="http://fotki.yandex.ru/users/alekna/album/63988/" rel="alternate" />
  <f:image-count value="10" />
  <link href="http://api-fotki.yandex.ru/api/users/alekna/album/63988/photos/updated;2009-01-27T11:57:06Z,126742/" rel="next" />
  <entry>...</entry>
  <entry>...</entry>
  ...
  <entry>...</entry>
</feed>

При сортировке "от новых к старым" постраничная выдача коллекции является устойчивой: она дает целостный одинаковый результат на момент начала выдачи, независимо от возможных изменений коллекции. Так пользователь не увидит новые элементы, добавленные в коллекцию после начала постраничной выдачи.

При сортировке "от старых к новым" новые элементы добавляются в конец выдачи, и клиентское приложение должно само заботиться об "обрезании" новых элементов коллекции при показе их пользователю. О том, изменилась ли коллекция за время постраничной выдачи, можно судить по значению атрибута atom:updated, который всегда содержит актуальные данные о времени последнего изменения коллекции.

Ошибки

• 400 Bad Request

  Неправильно указан параметр limit.

• 404 Not Found

  Запрашиваемый элемент коллекции отсутствует: неправильно указано значение параметра сортировки или неверно задано время.