API сервиса Подписки

Авторизация

Для авторизации пользователя используется протокол OAuth 2.0

Подробнее о процедурах авторизации через oauth.yandex.ru можно почитать в документации к данному сервису.

Ресурсы

API построено по REST-принципам.
Сущности, которыми можно управлять через API, представлены в виде ресурсов: список постов, данные о посте, подписки, поток, папка и т.п.
C этими ресурсами можно производить различные операции, например:

прочитать их содержимое и текущее состояние (GET)

изменить их содержимое и состояние и записать в ресурс (PUT)

удалить их (DELETE)

сделать что-то специальное, например, добавить новый элемент (POST)

У каждого ресурса есть свой уникальный URL.

Cписок всех ресурсов можно найти в справочнике ресурсов.

Регистрация пользователей

Любому зарегистрированному пользователю Яндекса сервис Подписок доступен в ограниченном режиме: пользователь может просмотреть содержимое потоков, запросив их по url или md5. Это полезно, например, для предварительного просмотра потока.

Чтобы начать пользоваться основными возможностями сервиса, нужно дополнительно зарегистрировать для пользователя учетную запись Подписок. Она дает возможность управлять своими подписками, следить за статусами сообщений (прочитано или нет), добавлять метки к постам и т.д. Для регистрации учетной записи нужно сделать пустой POST-запрос на ресурс /initiate.

URL'ы ресурсов по возможности не должны составляться вручную на клиентской стороне, а должны формироваться из ответов системы. В идеале о системе должен быть известен только один корневой URL, а всё остальное должно быть достижимо из него (на практике, как водится, это не всегда так).

Например, прочитав ресурс постов, можно получить полные URL'ы ресурсов до конкретных постов и их метаинформации, потоков и папок. Из URL'а списка потоков можно получить ссылку на конкретный поток и папку.

Форматы данных

Все ресурсы выдают и принимают данные в собственных xml-форматах (см. ниже). В комментариях к форматам опущены описания очевидных полей (author, title, id и т.д.).

Список постов

Content-Type: application/x-yandex-lenta+xml; type=posts

<posts>
  <current md5="1d45ed4b56f9c7a2a8af6e3f5c764425"/>
  <link href="https://api-lenta.yandex.ru/posts?nav=1d45ed4b56f9c7a2a8af6e3f5c764425.22629.1287983090
&read_status=any&items_per_page=20&md5=1d45ed4b56f9c7a2a8af6e3f5c764425" rel="next"/>
  <link href="https://api-lenta.yandex.ru/posts?nav=1d45ed4b56f9c7a2a8af6e3f5c764425.22669.1287983090
&read_status=any&items_per_page=20&md5=1d45ed4b56f9c7a2a8af6e3f5c764425" rel="previous"/>
  <subscriptions unread_count="00">
    <group unread_count="00" group_id="1">
      <title>Папка</title>
      <link href="https://api-lenta.yandex.net/subscriptions/groups/1"/>
    </group>
  </subscriptions>
  <feeds_data>
    <feed lang="rus" status="200" unread_count="10">
      <rate>4</rate>
      <md5>1d45ed4b56f9c7a2a8af6e3f5c764425</md5>
      <img_normal src="http://pix2.blogs.yandex.net/getavatar?id=2eijcek7n5.54
&prefix=normal" height="100" width="100"/>
      <img_middle src="http://pix2.blogs.yandex.net/getavatar?id=2eijcek7n5.54
&prefix=middle" height="50" width="50"/>
      <img_small src="http://pix2.blogs.yandex.net/getavatar?id=2eijcek7n5.54
&prefix=small" height="25" width="25"/>
      <description>абстрактный поток</description>
      <url href="http://username.livejournal.com/data/rss"/>
      <html href="http://username.livejournal.com/"/>
      <link href="https://api-lenta.yandex.ru/subscriptions/feeds/1d45ed4b56f9c7a2a8af6e3f5c764425"/>
      <favicon href="http://favicon.yandex.net/favicon/livejournal.com"/>
      <title>terapevt</title>
    </feed>
  </feeds_data>
  <post id="1d45ed4b56f9c7a2a8af6e3f5c764425.22649.1287983090">
    <meta href="https://api-lenta.yandex.ru/posts/1d45ed4b56f9c7a2a8af6e3f5c764425.22649.1287983090/meta"/>
    <content href="https://api-lenta.yandex.ru/posts/1d45ed4b56f9c7a2a8af6e3f5c764425.22649.1287983090"/>
    <archive/>
    <read/>
    <tags/>
    <comments_info count="0" last_time=""/>
    <entry>
    <link href="http://www.site.ru/index.shtml?2010/10/25/1601814"/>
    <comments href=""/>
    <id>http://www.site.ru/index.shtml?2010/10/25/1601814</id>
    <issued>2010-10-25T04:25:38Z</issued>
    <guid>http://www.site.ru/index.shtml?2010/10/25/1601814</guid>
    <first_line>Тут содержится какой-то контент</first_line>
    <title>Заголовок</title>
    <content type="xhtml">Тут содержится какой-то контент</content>
    <categories>
      <category>Новости</category>
    </categories>
    </entry>
  </post>
</posts>

current — содержит атрибут, указывающий, какая страница была запрошена.

md5 — страница потока

group_id — страница папки

tag_id — страница тэга

subscriptions — содержит подписки пользователя

feeds_data — содержит данные о потоке/ах, на которые пользователь не подписан

Далее следуют сообщения с контентом и метаинформацией

Содержимое поста

Content-Type: application/x-yandex-lenta+xml; type=post

<post id="807dba6d4f3a9d31e3785bfbe0144bea.1996.1288002433">
  <meta href="https://api-lenta.andex.ru/posts/807dba6d4f3a9d31e3785bfbe0144bea.1996.1288002433/meta"/>
  <content href="https://api-lenta.yandex.ru/posts/807dba6d4f3a9d31e3785bfbe0144bea.1996.1288002433"/>
  <feed href="https://api-lenta.yandex.ru/subscriptions/feeds/807dba6d4f3a9d31e3785bfbe0144bea"/>
  <comments_info count="3" last_time="2010-10-25T16:21:53"/>
  <author_data>
    <img_normal src="http://pix2.blogs.yandex.net/getavatar?id=bv7mc3ogil.4112
&prefix=normal" height="100" width="100"/>
    <img_middle src="http://pix2.blogs.yandex.net/getavatar?id=bv7mc3ogil.4112
&prefix=middle" height="50" width="50"/>
    <img_small src="http://pix2.blogs.yandex.net/getavatar?id=bv7mc3ogil.4112
&prefix=small" height="25" width="25"/>
    <html href="http://username.livejournal.com/"/>
    <title>username</title>
  </author_data>
  <entry>
    <link href="http://community.livejournal.com/community/531407.html"/>
    <comments href="http://community.livejournal.com/community/531407.html"/>
    <id>http://community.livejournal.com/community/531407.html</id>
    <author>http://username.livejournal.com/</author>
    <issued>2010-10-25T10:27:08Z</issued>
    <guid>http://community.livejournal.com/community/531407.html</guid>
    <first_line>Пример сообщения для API</first_line>
    <title>Заголовок</title>
    <content type="xhtml">Пример сообщения для API</content>
    <categories>
      <category>Новости</category>
    </categories>
    <mood>Тестовое настроение</mood>
    <music>музыка</music>
  </entry>
</post>

comments_info — информация о комментариях к посту

count — количество комментариев. Если count=0, возможен один из вариантов: либо комментариев у поста нет, либо в rss-потоке нет URL, откуда можно скачивать эти комментарии.

last_time — время последнего комментария.

img — аватарка автора поста разных размеров

html — url страницы автора

entry — данные о посте

link — ссылка на оригинальную версию поста

comments — ссылка на комментарии

issued — время написания поста

guid — cтрока, уникальным образом идентифицирующая пост

first_line — краткая версия поста для предварительного просмотра

title — заголовок

content — контент поста

enclosure — вложение, некий медиа-объект

categories — перечисление категорий, к которым относится данный пост

author_data — информация об авторе поста

meta — URL ресурса с метаданными поста

content — URL ресурса с контентом поста

feed — URL ресурса потока

Метаданные о посте

Content-Type: application/x-yandex-lenta+xml; type=post

<post id="b7be01f9245bd8ad4bd621cce4e7c2bf.1437.1288006441">
  <meta href="https://api-lenta.yandex.ru/posts/b7be01f9245bd8ad4bd621cce4e7c2bf.1437.1288006441/meta"/>
  <content href="https://api-lenta.yandex.ru/posts/b7be01f9245bd8ad4bd621cce4e7c2bf.1437.1288006441"/>
  <feed href="https://api-lenta.yandex.ru/subscriptions/feeds/b7be01f9245bd8ad4bd621cce4e7c2bf"/>
  <read/>
  <archive/>
  <favorite/>
  <tags>
    <tag href="https://api-lenta.yandex.ru/posts?items_per_page=20&read_status=any&nav=default&tag_id=4">тэг</tag>
  </tags>
</post>

Нижеперечисленные тэги можно редактировать.

read — наличие этого элемента обозначает, что пост прочитан, если отсутвует - непрочитан

archive — обозначает, что пост является архивным и его нельзя пометить как непрочитанный

favorite — его наличие означает, что пост отмечен как важный

tags — содержит список тегов, которыми отмечен пост. В элементе tag указывается название тэга и ссылка на список постов, помеченных этим тэгом.

meta — URL ресурса с метаданными поста

content — URL ресурса с контентом поста

feed — URL ресурса потока

Поток

Content-Type: application/x-yandex-lenta+xml; type=feed

<feed lang="rus" status="200" unread_count="2">
  <group_id href="https://api-lenta.yandex.ru/subscriptions/groups/1">1</group_id>
  <rate>1655</rate>
  <md5>b7be01f9245bd8ad4bd621cce4e7c2bf</md5>
  <img_normal src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=normal" 
height="100" width="100"/>
  <img_middle src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=middle" 
height="50" width="50"/>
  <img_small src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=small"
 height="25" width="25"/>
  <description/>
  <url href="http://clubs.ya.ru/club/rss/posts.xml"/>
  <html href="http://clubs.ya.ru/club/"/>
  <link href="https://api-lenta.yandex.ru/subscriptions/feeds/b7be01f9245bd8ad4bd621cce4e7c2bf"/>
  <favicon href="http://favicon.yandex.net/favicon/my.ya.ru"/>
  <title>Просто блог</title>
</feed>

group_id — папка, в которой лежит поток

lang — язык потока

status — статус при последнем обращении к потоку

unread_count — число непрочитанных постов в этом потоке

group_id — идентификатор папки, в которой данный поток лежит. Если отсутсвует, то поток лежит в корневой папке. Можно редактировать удаляя данный элемент или изменяя значение.

rate — число людей, читающий этот поток в ЯПодписках

md5 — идентификатор потока

img — аватарки блога в разном размере

description — описание

url — ссылка на URL потока

html — ссылка на страницу, на которой можно найти данный поток

favicon — ссылка на favicon потока

link — адрес ресурса данного потока

Папка

Content-Type: application/x-yandex-lenta+xml; type=group

<group unread_count="276" group_id="12">
  <title>Книги</title>
  <collapsed/>
  <link href="https://api-lenta.yandex.ru/subscriptions/groups/12"/>
</group>

unread_count — число непрочитанных сообщений в этой папке

collapsed — наличие этого элемента обозначает, что папка свернута. Его можно удалять и добавлять.

link — адрес ресурса данной папки

Подписки

Content-Type: application/x-yandex-lenta+xml; type=subscriptions

<subscriptions unread_count="10">
  <group unread_count="2" group_id="1">
    <title>Папка</title>
    <collapsed/>
    <link href="https://api-lenta.yandex.ru/subscriptions/groups/1"/>
    <feed lang="rus" status="200" unread_count="2">
      <rate>1655</rate>
      <md5>b7be01f9245bd8ad4bd621cce4e7c2bf</md5>
      <img_normal src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=normal" height="100" width="100"/>
      <img_middle src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=middle" height="50" width="50"/>
      <img_small src="http://pix2.blogs.yandex.net/getavatar?id=u2e7fg423t.2&prefix=small" height="25" width="25"/>
      <description/>
      <url href="http://clubs.ya.ru/club/rss/posts.xml"/>
      <html href="http://clubs.ya.ru/club/"/>
      <link href="https://api-lenta.yandex.ru/subscriptions/feeds/b7be01f9245bd8ad4bd621cce4e7c2bf"/>
      <favicon href="http://favicon.yandex.net/favicon/my.ya.ru"/>
      <title>Просто блог</title>
    </feed>
  </group>
  <feed lang="rus" status="200" type="blog" unread_count="8">
    <rate>2036</rate>
    <md5>fa7fb15516175bc5a5b085b321c5bbc1</md5>
    <img_normal src="http://pix2.blogs.yandex.net/getavatar?id=577az9dd0e.2&prefix=normal" height="100" width="100"/>
    <img_middle src="http://pix2.blogs.yandex.net/getavatar?id=577az9dd0e.2&prefix=middle" height="50" width="50"/>
    <img_small src="http://pix2.blogs.yandex.net/getavatar?id=577az9dd0e.2&prefix=small" height="25" width="25"/>
    <description>Пример потока livejournal.com</description>
    <url href="http://username.livejournal.com/data/rss"/>
    <html href="http://username.livejournal.com/"/>
    <link href="https://api-lenta.yandex.ru/subscriptions/feeds/fa7fb15516175bc5a5b085b321c5bbc1"/>
    <favicon href="http://favicon.yandex.net/favicon/livejournal.com"/>
    <title>username</title>
  </feed>
  <stat href="https://api-lenta.yandex.ru/stat"/>
  <settings href="https://api-lenta.yandex.ru/settings"/>
</subscriptions>

stat — url ресурса статистики с числом новых и непрочитанных сообщений

settings — url ресурса настроек пользователя

Собраны все подписки пользователя. Причем информация о потоках разложена по папкам, в которых они находятся.

Ресурс подписок используется для добавления новых потоков и папок.

Для этого нужно сделать POST-запрос с Content-Type: application/x-yandex-lenta+xml; type=feed, в котором передаётся описание потока (см. выше). Не все поля являются обязательными, достаточно указать источник потока (url или md5). Также можно сразу указать группу и альтернативное название. Например:

<feed>
  <url>http://username.livejournal.com/</url>
  <group_id>1</group_id>
  <title>Название</title>
</feed>

Для того чтобы добавить новую папку пользователю, необходимо сделать POST-запрос с Content-Type: application/x-yandex-lenta+xml; type=group

<group>
  <title>бла</title>
</group>

Ресурс подписок также используется для пометки потока или папки как прочитанные.

Для того чтобы пометить папку или поток прочитанными, необходимо сделать POST-запрос с Content-Type: application/x-yandex-lenta+xml; type=read

Пометить поток как прочитанный:

<read>
  <md5>2342f5186e6b49d66d647f0f205835c9</md5>
</read>

Пометить папку как прочитанную:

<read>
  <group_id>14</group_id>
</read>

Настройки

Content-Type: application/x-yandex-lenta+xml; type=settings

<settings>
  <default_group>all</default_group>
</settings>

default_group — папка пользователя по умолчанию. Это либо целое число — идентификатор группы, либо all — идентификатор, обозначающий чтение всех потоков подряд. Может быть отредактировано.

Статистика

Content-Type: application/x-yandex-lenta+xml; type=stat

<stat>
  <unread href="https://api-lenta.yandex.ru/stat/unread">3000</unread>
  <new href="https://api-lenta.yandex.ru/stat/new">6</new>
</stat>

unread — число непрочитанных сообщений

new — число новых сообщений, т.е. число непрочитанных сообщений пользователя с момента его последней активности на сервисе.

Обращение к ресурсу статистики может быть более "затратным", чем к отдельным ресурсам новых и непрочитанных сообщений. Поэтому, если необходимо только одно из этих чисел, лучше использовать отдельный ресурс (или новых, или непрочитанных сообщений).

Число непрочитанных сообщений

Content-Type: application/x-yandex-lenta+xml; type=stat

<stat>
  <unread href="https://api-lenta.yandex.ru/stat/unread">3000</unread>
</stat>

Число новых сообщений

Content-Type: application/x-yandex-lenta+xml; type=stat

<stat>
  <new href="https://api-lenta.yandex.ru/stat/new">6</new>
</stat>

Паджинация

В списке постов присутствуют элементы <link href="..." rel="next"/> и <link href=".." rel="previous"/>. Это указатели на следующую и предыдущую страницы.

В случае, если один из этих элемент присутствует в выдаче, значит, список выдан не полностью, и по URL из атрибута href можно получить остальное. Методика выборки полного списка такая: выбирать списки один за другим, пока в них есть этот атрибут.

Примеры

Получить число новых сообщений

GET /stat/new HTTP/1.1
Host: api-lenta.yandex.ru
Content-type: application/x-yandex-lenta+xml; type=stat; charset=utf-8
Authorization: OAuth nA8bhk6qfL

HTTP/1.1 200 OK
Content-Length: 107
Etag: "c1840734ab228e13c24a55d54240208c437768eb"
Content-Type: application/xml; charset=UTF-8
Server: TornadoServer/0.1
Date: Wed, 10 Nov 2010 10:59:27 GMT

<?xml version="1.0" encoding="utf-8"?><stat><new href="https://api-lenta.yandex.ru/stat/new">8</new></stat>

Подписаться на поток

POST /subscriptions HTTP/1.1
Host: api-lenta.yandex.ru
Content-Type: application/x-yandex-lenta+xml; type=feed; charset=utf-8
Content-Length: 74
Authorization: OAuth nA8bhk6qfL

<feed><url>http://tema.livejournal.com/</url><group_id>1</group_id></feed>

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/xml; charset=UTF-8
Server: TornadoServer/0.1

<?xml version="1.0" encoding="utf-8"?><ok/>

Справочник

Хосты

API: https://api-lenta.yandex.ru

OAuth-авторизация: https://oauth.yandex.ru

Ресурсы

Таблица, приведенная ниже, содержит описание всех ресурсов со всеми доступными для них методами.


Ресурс	URL	Методы	Комментарии

Список постов	/posts?{group_id,md5,url,tag_id}&nav&items_per_page&read_status	GET	Из `group_id`, `md5`, `url`, `tag_id` должен быть указан только один. Параметры `nav`, `items_per_page`, `read_status` - необязательные

Содержимое поста	/posts/{md5.item_no.store_time}	GET

Метаданные о посте	/posts/{md5.item_no.store_time}/meta	GET, PUT

Подписки	/subscriptions	GET, POST	application/x-yandex-lenta+xml; type=feed или application/x-yandex-lenta+xml; type=group или application/x-yandex-lenta+xml; type=read

Поток	/subscriptions/feeds/{md5}	GET, PUT, DELETE

Папка	/subscriptions/groups/{group_id}	GET, PUT, DELETE	`group_id` - только целое число

Настройки	/settings	GET, PUT

Статистика	/stat, /stat/new, /stat/unread	GET

Инициализация нового пользователя	/initiate	POST

Описание параметров

group_id — идентификатор группы, либо целое число, либо all

md5 — идентификатор потока

url — URL потока

tag_id — идентификатор тэга, а также значение favorite(можно получить все важные сообщения)

nav — строка навигации. Принимает значение default или внутренний id поста (id из атрибута элемента post).

items_per_page — число запрошенных постов

read_status — статус запрашиваемой страницы, принимает 2 значения:

any — выдавать все посты

unread — выдать только непрочитанные посты

Ошибки

Http-код	сообщение	комментарий


400	Argument arg must be integer	неправильный тип аргумента

400	Argument arg required	аргумент обязательно должен быть указан

400	Bad xml document	невалидный xml-документ

400	Root tag in request request_root_tag don't match with root_tag	в полученном xml-документе неправильный корневой элемент

400	Must be either group_id or url or md5 or tag_id	Должен быть указан только один параметр из списка: `group_id`, `url`, `md5`, `tag_id`

400	Must be either url or md5	должен быть указан `url` или `md5`

400	Must be either md5 or group_id	должен быть указан `feed` или `group`

400	md5 in url and md5 in body don't match	`md5` в xml-документе не совпадает с `md5` в адресе ресурса

400	group_id in url and group_id in body don't match	`group_id` в xml-документе не совпадает с `group_id` `в адресе ресурса`

400	Failed to resolve feed :	такой поток не найден

400	Missing parameter	пропущен параметр, указывается в сообщении

400	Invalid parameter	параметру передано неправильное значение

400	Not found group with group_id	папка не найдена

400	Group with group_title existed	папка с таким названием уже есть

400	Failed to get item store_time	не удалось получить store_time

400	Not found tag with tag_id	тэг не найден

401	token expired или authorization required	содержит header `WWW-Authenticate: OAuth realm="lenta",` `error="error"`, проблемы с токеном - закончился срок действия или нет такого токена

403	User is not subscribed to the service	пользователь не иcпользует данный сервис

404	Not Found	не найден

405	Method Not Allowed	метод не разрешен

415	Header Content-Type must be	указан неподдерживаемый заголовок Content-Type

504		таймаут соединения

502		сервер получил некорректный ответ

503		сервер временно недоступен

премодерируемый клуб

API сервиса Подписки

Авторизация

Ресурсы

Регистрация пользователей

Навигация

Форматы данных

Список постов

Содержимое поста

Метаданные о посте

Поток

Папка

Подписки

Настройки

Статистика

Число непрочитанных сообщений

Число новых сообщений

Паджинация

Примеры

Получить число новых сообщений

Подписаться на поток

Справочник

Хосты

Ресурсы

Описание параметров

Ошибки


	Отписаться от комментарев к записи
	Получать уведомления только о тех ответах в этом обсуждении, которые адресованы лично вам. Форма не заполнена

Найдены:

премодерируемый клуб

API сервиса Подписки

выделить все / снять выделение

Авторизация

Ресурсы

Регистрация пользователей

Навигация

Форматы данных

Список постов

Содержимое поста

Метаданные о посте

Поток

Папка

Подписки

Настройки

Статистика

Число непрочитанных сообщений

Число новых сообщений

Паджинация

Примеры

Получить число новых сообщений

Подписаться на поток

Справочник

Хосты

Ресурсы

Описание параметров

Ошибки