Renoter API

Введение

Ренотер предоставляет доступ к части своего функционала через Интерфейс Программирования Приложений (API). Этот документ содержит в себе описание доступных методов API и призван помочь разработчикам, пишущим утилиты для Ренотера.

Содержание

Введение
Содержание
Общие положения
1. Аутентификация
2. Изменения в API
Методы получения статусов
Методы управления аккаунтом
1. Тест авторизации
Возвращаемые элементы
1. Элемент статуса
2. Расширенный элемент пользователя
Возвращаемые значения

Общие положения

Аутентификация

Многие методы настоящего API требуют аутентификации. Речь идет о логине и пароле, используемом на сайте. Необходимо это например для того чтобы создать новый статус в рамках аккаунта конкретного пользователя.

В качестве основного метода мы используем HTTP Basic Authentication. В качестве логина может использоваться логин пользователя на сайте или активный подтвержденный email.

Изменения в API

Информация о каждом изменении в настоящем API, а так же добавлении/удалении определенных методов транслируется RSS потоком, а так же описывается в статусном блоге. После первой информации об изменении/удалении какого-либо метода, сохраняется совместимость между старым и новым вариантом (или метод не удаляется) в течение 2х недель.

Методы получения статусов

Последние открытые статусы

Описание: Возвращает 20 последних открытых статусов. Не требует авторизации. Результат кешируется на 5 секунд.

URL: http://renoter.com/statuses/public_timeline.format

Форматы: xml, json, rss, atom

Метод запроса: GET

Параметры: отсутствуют

Результат: список элементов статуса

Статусы друзей

Описание: Возвращает 20 последних статусов друзей. Результат аналогичен выводу на странице /home. Требует авторизации.

URL: http://renoter.com/statuses/friends_timeline.format

Форматы: xml, json, rss, atom

Метод запроса: GET

Параметры:

since

Опциональный. Дата написания статусов. При указании, будут выбраны статусы, написание в течение 24 часов после указанной даты. Может быть указан в секундах вида UNIX_TIME или в любом формате, описанном в документе. Примеры:

http://renoter.com/statuses/friends_timeline.xml?since=1238101200
http://renoter.com/statuses/friends_timeline.xml?since=Fri,%2027%20Mar%202009%2014:10:07%20+0300
http://renoter.com/statuses/friends_timeline.xml?since=-1%20day (все статусы за последние сутки)

since_id

Опциональный. Будут возвращены только статусы с ID большим указанного. Пример:
http://renoter.com/statuses/friends_timeline.xml?since_id=55248

max_id

Опциональный. Будут возвращены только статусы с ID меньшим указанного. Пример:
http://renoter.com/statuses/friends_timeline.xml?max_id=55248

count

Опциональный. Количество статусов на одной странице. Может быть не более 200. Пример:
http://renoter.com/statuses/friends_timeline.xml?count=10

page

Опциональный. Страница результатов запроса. Пример:
http://renoter.com/statuses/friends_timeline.json?page=7

Результат: список элементов статуса

Статусы пользователя

Описание: Возвращает 20 последних статусов указанного пользователя с учетом прав доступа авторизованного пользователя. Результат аналогичен выводу на странице указанного пользователя. Авторизация может использоваться.

URL: http://renoter.com/statuses/user_timeline.format

Форматы: xml, json, rss, atom

Метод запроса: GET

Параметры:

user_id

Опциональный, если указан login. ID пользователя, чьи статусы необходимо получить. Пример:
http://renoter.com/statuses/user_timeline.xml?user_id=25

login

Опциональный, если указан user_id. Если указаны оба, то будет использовано значение user_id. Логин пользователя, чьи статусы необходимо получить. Регистронезависим. Пример:
http://renoter.com/statuses/user_timeline.xml?login=renoter

since

http://renoter.com/statuses/user_timeline.xml?since=1238101200
http://renoter.com/statuses/user_timeline.xml?since=Fri,%2027%20Mar%202009%2014:10:07%20+0300
http://renoter.com/statuses/user_timeline.xml?since=-1%20day (все статусы за последние сутки)

since_id

Опциональный. Будут возвращены только статусы с ID большим указанного. Пример:
http://renoter.com/statuses/user_timeline.xml?since_id=55248

max_id

Опциональный. Будут возвращены только статусы с ID меньшим указанного. Пример:
http://renoter.com/statuses/user_timeline.xml?max_id=55248

count

Опциональный. Количество статусов на одной странице. Может быть не более 200. Пример:
http://renoter.com/statuses/user_timeline.xml?count=10

page

Опциональный. Страница результатов запроса. Пример:
http://renoter.com/statuses/user_timeline.json?page=7

Результат: список элементов статуса

Получение статуса

Описание: Получает статус и его автора. ID статуса указывается в адресе запроса. Авторизация может использоваться для получения отметки о наличии статуса в закладках и доступа к скрытым статусам.

URL: http://renoter.com/statuses/show/id.format

Форматы: xml, json

Метод запроса: GET

Параметры:

id: Обязательный. ID запрашиваемого статуса.

Результат: один элемент статуса

Создание статуса

Описание: Создает новый статус для авторизованного пользователя. Передается методом POST. Текст статуса необходимо передать в параметре. Авторизация необходима.

URL: http://renoter.com/statuses/update.format

Форматы: xml, json

Метод запроса: POST

Параметры:

status: Обязательный. Текст статуса. Ссылки в тексте длной свыше 25 символов будут укорочены, итоговая длина текста будет уменьшена до 140 символов.
in_reply_to_status_id: Опциональный. Указывает на id статуса, которому предназначается новый в качестве ответа. Если статус с указанным ID не существует, то параметр будет проигнорирован.
preview: Опциональный. Адрес изображения, которое нужно загрузить как превью к статусу.

Результат: новый элемент статуса

Удаление статуса

Описание: Удаляет статус с указанным ID. Авторизация необходима.

URL: http://renoter.com/statuses/destroy/id.format

Форматы: xml, json

Метод запроса: POST

Параметры:

id: Обязательный. id удаляемого статуса, например http://renoter.com/statuses/destroy/5273.json.

Результат: удаленный элемент статуса

Методы управления аккаунтом

Тест авторизации: Описание: Возвращает HTTP 200 OK код, если авторизационные данные пользователя верны. В противном случае возвращает ошибку в теле ответа и код 401 Unauthorized в заголовке.; URL: http://renoter.com/account/verify_credentials.format; Форматы: xml, json; Метод запроса: GET; Параметры: отсутствуют; Результат: единственный расширенный элемент пользователя

Возвращаемые элементы

Существует четыре стандартных элемента, возвращаемых в результате тех или иных запросов. В описании каждого запроса указан элемент, который будет возвращен.

Элемент статуса

Этот элемент описывает один статус, а также пользователя (<user>), являющегося автором статуса.

<status>

in_reply_to_status_id

in_reply_to_user_id

in_reply_to_user_login

favorited

<user>: id; name; login; description; location; website; profile_image_url; protected; followers_count; friends_count; updates_count

Расширенный элемент пользователя

Этот элемент полностью описывает одного пользователя.

Возвращаемые значения

created_at: Описание: Время создания элемента, пользователя или статуса в формате RFC 2822; Пример: Sat, 04 Sep 2010 06:01:59 +0000
created_in_seconds: Описание: Время создания элемента, пользователя или статуса в секундах, начиная с 1 января 1970 года, 00:00:00 GMT; Пример: 1283580119
id: Описание: Порядковый номер элемента, пользователя или статуса. Уникален для каждой сущности; Пример: 8762933
text: Описание: Текст статуса. Предельная длина 140 символов. Экранированы основные html-сущности; Пример: Тег будет выглядеть как <tag>, одинарная кавычка -- ', двойная -- "
source: Описание: Программа/место откуда был отправлен статус; Пример: <a href="http://help.renoter.com/sms">SMS</a>
preview_image: Описание: Адрес до уменьшенной копии изображения, если на него есть ссылка в тексте статуса; Пример: http://assets1.renoter.com/preview/1.png
in_reply_to_status_id: Описание: id статуса, на который отвечает полученный статус; Пример: 8764535
in_reply_to_user_id: Описание: id пользователя, являющегося автором статуса, на который отвечает полученный статус; Пример: 32955
in_reply_to_user_login: Описание: login пользователя, являющегося автором статуса, на который отвечает полученный статус; Пример: Example
favorited: Описание: Информация о том, находится ли полученный статус в закладках авторизованного пользователя. Тип boolean. Для неавторизованного пользователя всегда false; Пример: false, true
name: Описание: Имя пользователя, указанное им в настроках. До 40 символов; Пример: Иван Величев
login: Описание: Логин пользователя, используемый для аутентификации и отображаемый у каждого собственного сообщения на сайте; Пример: Movie, example
description: Описание: Описание пользователя, указанное им в настройках аккаунта. До 200 символов; Пример: Programmer
location: Описание: Местоположение пользователя, указанное им в настройках аккаунта. До 200 символов; Пример: Работу работаю на работе
website: Описание: Персональный сайт пользователя, указанный в настройках аккаунта. До 200 символов; Пример: http://example.com/white_man
profile_image_url: Описание: URL до аватара пользователя, использующегося на сайте; Пример: http://assets1.renoter.com/ava/c4/ca/42/1_5890_medium.png
protected: Описание: Переменная типа boolean устанавливается в true, когда статусы пользователя закрыты для неприсоединенных пользователей; Пример: true, false
followers_count: Описание: Количество пользователей присоединившихся к выбираемому пользователю; Пример: 0, 26
friends_count: Описание: Количество пользователей, к которым присоединился указанный пользователь; Пример: 0, 63
updates_count: Описание: Количество статусов, написанных пользователем; Пример: 0, 426
profile_background_color: Описание: Цвет собственной страницы, выбранный пользователем, в формате RGB; Пример: 23fa34, ffffff
profile_text_color: Описание: Цвет текста на собственной странице, выбранный пользователем, в формате RGB; Пример: 000000, ff7777
profile_link_color: Описание: Цвет ссылок на собственной странице, выбранный пользователем, в формате RGB; Пример: 002099, 5555ff
profile_sidebar_fill_color: Описание: Цвет боковой панели собственной страницы, выбранный пользователем, в формате RGB; Пример: 333000, ddffdd
profile_sidebar_border_color: Описание: Цвет разделительных линий на боковой панели в профиле, выбранный пользователем, в формате RGB; Пример: ffffff, 009900
profile_background_image_url: Описание: Адрес изображения, использующегося в качестве фонового на странице пользователя; Пример: http://renoter.com/i/theme-bg6.jpg
profile_background_tile: Описание: Boolean. true говорит о том, что фоновое изображение дублируется по горизонтали и вертикали в профиле пользователя. false о том, что фоновое изображение в единственном экземпляре прикреплено к левому верхнему углу страницы; Пример: true, false
time_zone: Описание: Временная зона, установленная пользователем; Пример: Europe/Moscow
relation: Описание: Отношение авторизованного пользователя к выбранному. Поддерживаются 4 варианта: follow, no_follow, request, block; Пример: follow, no_follow
online: Описание: Boolean. Говорит о том, были ли любые запросы к сервису от выбираемого пользователя за последние 4 минуты.; Пример: true, false