API

Материал из Справка @diary.ru.

Перейти к: навигация, поиск

API - (application programming interface) интерфейс программирования приложений.

Содержание

[править] Формат запроса

запрос

www.diary.ru/api/?method=[method]&[param1]=[val1]&[param2]=[val2]&...

Запрос может быть GET или POST. Для создания и редактирования записей и комментариев POST предпочтительнее, поскольку предоставляет возможность прикреплять изображения и отправлять более длинный текст самого сообщения. Все ответы в этом и в остальных запросах приходят в формате JSON.

ответ:

result:
  • 0 - успешно
  • другое - код ошибки, при этом:
error:
  • текстовое описание ошибки.

[править] Авторизация

[править] Метод
user.auth
[править] Описание

Метод позволяет пройти авторизацию на сервисе. В ответ приходит индентификатор сессии (SessionID или sid), использование которого позволяет осуществлять взаимодействие с сервисом. Срок действия sid - 20 минут с последнего действия. По истечении срока действия sid его необходимо переполучить.

Каждый разработчик получает открытый и закрытый ключи, которые используются для шифрования и передачи пароля. Запрос на получение ключей следует отправлять нам на почту info@co.diary.ru.

При авторизации используется кодировка win1251. Логин пользователей с кириллическими символами следует передавать в кодировке url-encode(win1251), а не url-encode(utf-8). Более подробно рассказывается здесь.


[править] Параметры
  • username - логин пользователя
  • password - зашифрованный пароль
  • appkey - уникальный ключ приложения
[править] Ответ
  • sid - идентификатор сессии

[править] Работа с данными пользователя

[править] Получение информации

[править] Получение информации о пользователе

[править] Метод
user.get
[править] Параметры
  • sid - идентификатор сессии;
  • [userid] - идентификатор запрашиваемого пользователя, при отсутствии значения возвращается профиль текущего юзера;
  • [fields] - список полей через ",", которые необходимо получить (по умолчанию - все поля);
  • [unset] - список полей через ",", которые не должны быть в выводе метода.
[править] Ответ
  • userid – идентификатор пользователя;
  • username – имя пользователя (логин);
  • shortname – короткое имя пользователя;
  • journal - тип дневника
0 – нет,
1 - дневник,
2 – сообщество;
  • country - страна проживания;
  • region – регион проживания;
  • city – город;
  • homepage – домашняя страница;
  • sex – пол;
  • education – образование;
  • sfera – сфера деятельности;
  • avatar – аватар;
  • joindate – дата регистрации;
  • email – эл.почта;
  • icq;
  • birthday – день рождения;
  • favs2 – избранные (userid, username);
  • readers2 – постоянные читатели (userid, username);
  • mycommunity.members2 – члены сообщества (userid, username);
  • mycommunity.masters2 – владельцы сообщества (userid, username);
  • mycommunity.moderators2 – модераторы сообщества (userid, username);
  • community.member2 – член сообществ (userid, journal_title);
  • interest – интересы;
  • about – о себе.

[править] Получение информации о дневнике

[править] Метод
journal.get
[править] Параметры
  • sid - идентификатор сессии;
  • [userid] - идентификатор запрашиваемого пользователя, при отсутствии - возвращается профиль текущего юзера;
  • [shortname] – короткое имя пользователя;
  • [fields] - список полей через ",", которые необходимо получить (по умолчанию - все поля);
  • [unset] - список полей через ",", которые не должны быть в выводе метода.
[править] Ответ
  • userid – идентификатор пользователя;
  • shortname – короткое имя дневника;
  • jtype - тип дневника:
1 - дневник,
2 – сообщество;
  • ctime - дата создания;
  • title - название дневника;
  • posts - количество записей;
  • last_post - дата последней записи;
  • last_post_id - идентификатор последней записи;
  • count_pch - количество читателей;
  • count_members - количество участников (для сообществ);
  • tags - избранные теги;
  • access - степень закрытости дневника:
0 - открыт для всех,
1 - открыт для избранных,
2 - открыт для зарегистрированных пользователей,
3 - открыт для списка,
4 - закрыт для списка,
+10 - содержит материалы для взрослых.

[править] Добавление в избранное, удаление из избранного

[править] Добавление дневника в избранное

[править] Метод
favorite.add
[править] Параметры
  • sid - идентификатор сессии;
  • userid - идентификатор добавляемого пользователя.

[править] Удаление дневника из избранного

[править] Метод
favorite.del
[править] Параметры
  • sid - идентификатор сессии;
  • userid - идентификатор удаляемого пользователя.

[править] Работа с записями

[править] Получение набора записей

[править] Метод
post.get
[править] Параметры
  • sid - идентификатор сессии;
  • type - тип запрашиваемого содержимого:
diary - дневник/сообщество,
favorites - избранное,
quotes - цитатник,
notepad - блокнот,
draft - черновики,
last - последние записи,
by_id - по списку идентификаторов записей (postid), не более 100 за один запрос:
параметр ids - идентификаторы перечисляются через запятую;
  • [juserid]/[shortname] – идентификатор дневника / короткое имя пользователя, раздел дневника которого запрашивается, если не указано - запрос выполняется для текущего пользователя;
  • [from] - начало выборки;
  • [src] - тип получаемых записей:
0 – (по умолчанию) запись, готовая для вывода,
1 - исходный текст записи;
  • [fields] - список полей через ",", которые необходимо получить (по умолчанию - все поля);
  • [unset] - список полей через ",", которые не должны быть в выводе метода.
[править] Ответ
  • postid - идентификатор записи;
  • dateline_date - дата публикации записи;
  • dateline_cdate - дата первой публикации (для поднятых записей);
  • comments_count_data - количество комментариев;
  • juserid - идентификатор дневника;
  • shortname - короткое имя дневника;
  • journal_name - название дневника (для типов: last, quote, favorite);
  • subscribed - статус подписки текущего пользователя на дискуссию в записи;
  • close_access_mode - степень закрытости записи:
0 - открыта для всех,
1 - открыта для избранных,
2 - закрыта для списка,
3 - открыта для списка,
4 - открыта для белого списка,
5 - открыта для постоянных читателей,
6 - открыта для зарегистрированных пользователей,
7 - закрыта для всех (в случае сообщества - для всех, кроме владельцев и модераторов),
8 - (для сообщества) открыта только для членов сообщества;
  • close_access_mode2 - способ закрытия записи:
+10 - материалы для взрослых;
  • jaccess - степень закрытости дневника:
0 - открыт для всех,
1 - открыт для избранных,
2 - открыт для зарегистрированных пользователей,
3 - открыт для списка,
4 - закрыт для списка,
+10 - содержит материалы для взрослых;
  • message_src - исходный текст записи (доступен только для своих записей, необходим для редактирования);
  • tags_data - теги записи;
  • current_music - музыка;
  • current_mood - настроение;
  • author_userid - идентификатор автора записи;
  • author_shortname - короткое имя дневника автора записи;
  • author_username - логин автора записи;
  • author_title - подпись автора записи;
  • avatar_path - аватар автора записи;
  • title - заголовок записи;
  • message_html - текст записи;

В зависимости от параметра src:

  • no_smile - не преобразовывать смайлы в графический образ;
  • no_comments - без комментариев;
  • access_list - список доступа;
  • poll_title - вопрос;
  • poll_multiselect - тип голосования;
  • poll_end - признак окончания голосования;
  • poll_answer_{1..10} - ответы.

[править] Добавление записи

[править] Метод
post.create
[править] Параметры
  • sid - идентификатор сессии;
  • message/message_src - сообщение (параметр message_src используется для совместимости с методом post.get);
  • [juserid] - ID дневника (по умолчанию - свой дневник);
  • [type] - тип содержимого:
не указано - дневник/сообщество,
notepad - блокнот,
draft - черновики;
  • [title] - заголовок;
  • [no_comments] - без коментариев;
  • [no_smile] - без смайлов;
  • [close_access_mode] - способ закрытия записи:
0 - открыта для всех,
1 - открыта для избранных,
2 - закрыта для списка,
3 - открыта для списка,
4 - открыта для белого списка,
5 - открыта для ПЧ,
6 - открыта для зарегистрированных,
7 - закрыта для всех кроме владельцев и модераторов,
8 - открыта для членов сообщества;
  • [access_list] - список доступа - логины через \n;
  • [close_access_mode2] - способ закрытия записи:
10 - для взрослых;
  • [br_replace] - заменять переносы строк;
  • [current_music] - музыка;
  • [current_mood] - настроение;
  • [avatarid] - аватар (доступно при подключении соответствующего сервиса);
  • [poll_title] - голосование - вопрос;
  • [poll_answer_{1..10}] - голосование - ответы;
  • [poll_multiselect] - голосование - многовариантыный;
  • [tags] - темы;
  • [atags] - авто-темы, темы выделяются из текста записи автоматически по шаблону @[тема];
  • [dateline] - дата создания (в формате unix timestamp);
  • [attachment] - прикрепленное изображение;
  • [tags_data] - массив тем (совместим с post.get).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия;
  • postid - идентификатор новой записи.

[править] Редактирование записи

[править] Метод
post.update
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • message/message_src - сообщение (параметр message_src используется для совместимости с методом post.get);
  • [juserid] - ID дневника - поумолчанию свой дневнике;
  • [type] - тип содержимого - служит только для определения места записи, переносить записи редактируя это свойство не получится (поумолчанию - дневник/сообщество, notepad - блокнот, draft - черновики);
  • [title] - заголовок;
  • [no_comments] - без коментариев;
  • [no_smile] - без смайлов;
  • [close_access_mode] - способ закрытия записи:
0 - открыта для всех,
1 - открыта для избранных,
2 - закрыта для списка,
3 - открыта для списка,
4 - открыта для белого списка,
5 - открыта для ПЧ,
6 - открыта для зарегистрированных,
7 - закрыта для всех кроме владельцев и модераторов,
8 - открыта для членов сообщества;
  • [access_list] - список доступа - логины через \n;
  • [close_access_mode2] - способ закрытия записи:
10 - для взрослых;
  • [br_replace] - заменять на переносы строки;
  • [current_music] - музыка;
  • [current_mood] - настроение;
  • [avatarid] - аватар (доступно при подключении соответствующего сервиса);
  • [poll_title] - голосование - вопрос;
  • [poll_answer_{1..10}] - голосование - ответы;
  • [poll_end] - завершить голосование;
  • [poll_del] - удалить голосование;
  • [poll_multiselect] - голосование - многовариантыный;
  • [tags] - темы;
  • [atags] - авто-темы, темы выделяются из текста записи автоматически по шаблону @[тема];
  • [changedate] - сделать запись новой;
  • [attachment] - прикрепленное изображение;
  • [tags_data] - массив тем (совместим с post.get).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Удаление записи

[править] Метод
post.delete
[править] Параметры
  • sid - идентификатор сессии;
  • juserid - ID дневника;
  • postid - идентификатор записи;
  • [type] - тип содержимого:
не указано - дневник/сообщество,
notepad - блокнот,
draft - черновики.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Дискуссии в записи

[править] Подписка на дискуссии в записи

[править] Метод
post.subscribe
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Отписка от дискуссий в записи

[править] Метод
post.unsubscribe
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Запись в цитатнике

[править] Добавление записи в цитатник

[править] Метод
post.quoteadd
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор добавляемой записи.

[править] Удаление записи из цитатника

[править] Метод
post.quotedel
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор удаляемой записи.

[править] Изменение местоположения записи

[править] Поднятие записи

[править] Метод
post.up
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Возвращение записи после поднятия

[править] Метод
post.down
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Голосования

[править] Завершение голосования

[править] Метод
post.poll.end
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Удаление голосования

[править] Метод
post.poll.del
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • juserid - идентификатор дневника.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Работа с комментариями

[править] Получение набора комментариев

[править] Метод
comment.get
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • [from] - начало выборки;
  • [fromdateline] - начало выборки по дате комментирования;
  • [fields] - список полей через ",", которые необходимо получить (по умолчанию - все поля);
  • [unset] - список полей через ",", которые не должны быть в выводе метода.

Если параметр [from] в запросе не указан, то выводятся все комментарии к записи. Если же указан, то выводятся 30 комментариев, начиная с [from]+1-го (или все оставшиеся комментарии, если их менее 30).

[править] Ответ
  • commentid - идентификатор комментария;
  • dateline - дата отправки комментария;
  • can_edit - разрешение на редактирование и удаление;
  • ip - ip, с которого отправлен комментарий (доступен при подключении соответствующего сервиса);
  • message_html - текст комментария;
  • message_src - исходный текст (доступен для своих комментариев, необходим для редактирования);
  • author_userid - идентификатор автора;
  • author_username - логин автора;
  • author_avatar - аватар автора;
  • author_title - подпись автора;
  • author_shortname - короткое имя автора;
  • author_jtype - тип дневника автора:
0 - без дневника,
1 - дневник,
2 - сообщество.

[править] Создание комментария

[править] Метод
comment.create
[править] Параметры
  • sid - идентификатор сессии;
  • postid - идентификатор записи;
  • message - сообщение;
  • [dateline] - дата создания (в формате unix timestamp);
  • [no_smile] - без смайлов;
  • [br_replace] - заменять на переносы строки;
  • [avatarid] - аватар (доступно при подключении соответствующего сервиса);
  • [write_from] - написать от:
1 - от гостя;
2 - от другого пользователя:
[write_from_name],
[write_from_pass];
  • [subscribe] - подписать автора на комментарии;
  • [attachment] - прикрепленное изображение;
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Редактирование комментария

[править] Метод
comment.update
[править] Параметры
  • sid - идентификатор сессии;
  • commentid - идентификатор комментария;
  • message - сообщение;
  • [avatarid] - аватар (доступно при подключении соответсвующего сервиса);
  • [no_smile] - без смайлов;
  • [br_replace] - заменять на переносы строки;
  • [attachment] - прикрепленное изображение;
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Удаление комментария

[править] Метод
comment.delete
[править] Параметры
  • sid - идентификатор сессии;
  • commentid - идентификатор комментария.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Работа с уведомлениями

[править] Получение уведомлений

[править] Метод
notification.get
[править] Описание

Получение уведомлений u-mail, дискуссий, комментариев в своем дневнике. Каждый запрос может получить не более 100 объектов каждого типа независимо от их общего количества (указанного в счетчике count). Каждый следующий запрос получает общий счетчик непрочитанных только на новые объекты. Запросы на обновление кэшируются раз в 3 минуты: т.е. независимо от реального изменения новые данные функция сможет получать не чаще, чем раз в 3 минуты - и именно с таким интервалом стоит делать запросы на получение обновлений.

[править] Параметры
  • sid - идентификатор сессии.
[править] Ответ
  • discuss_count - общее число непрочитанных комментариев в дискуссиях;
  • discuss - дискусии:
discuss.juserid - идентификатор дневника;
discuss.postid - идентификатор записи;
discuss.dateline - дата последнего комментария;
discuss.count - количество непрочитанных комментариев в записи;
discuss.journal_name - название дневника/сообщества;
  • comments_count - общее число непрочитанных комментариев в дневнике;
  • comments - комментарии:
comments.postid - идентификатор записи;
comments.message_txt - начало (первые 100 символов) текста комментария;
  • umail_count - общее число непрочитанных писем u-mail;
  • umail - непрочитанные письма:
umail.umailid - идентификатор письма;
umail.from_userid - идентификатор отправителя;
umail.from_username - логин отправителя;
umail.dateline - дата-время отправления;
umail.message_txt - начало (первые 100 символов) текста письма;
umail.title - заголовок письма;
umail.folder - идентификатор папки.

[править] Сброс счётчиков

[править] Сброс счётчика непрочитанных диcкуccий

[править] Метод
notification.drop_discuss
[править] Параметры
  • sid - идентификатор сессии;
  • [type] - тип запроса на сброс:
all - (значение по умолчанию) все дискусии,
journal - сброс дискуссий по идентификатору дневника,
post - по идентификатору записи;
  • [id] - идентификатор (postid или juserid).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Сброс счётчика новых комментариев в дневнике

[править] Метод
notification.drop_comments
[править] Параметры
  • sid - идентификатор сессии;
  • [postid] - идентификатор записи (по умолчанию - во всех записях).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Сброс счётчика непрочитанных писем u-mail

[править] Метод
notification.drop_umail
[править] Параметры
  • sid - идентификатор сессии;
  • [umailid] - идентификатор письма (по умолчанию - все письма помечаются прочитанными).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Сброс всех счётчиков

[править] Метод
notification.drop_all
[править] Параметры
  • sid - идентификатор сессии;
дискусии:
  • [type] - тип запроса на сброс:
all - (значение по умолчанию) все дискусии,
journal - сброс дискуссий по идентификатору дневника,
post - по идентификатору записи;
  • [id] - идентификатор (postid или juserid);
комментарии:
  • [postid] - идентификатор записи (по умолчанию - счётчик сбрасывается во всех записях);
письма:
  • [umailid] - идентификатор письма (по умолчанию - все письма помечаются прочитанными).
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Работа с u-mail

[править] Получение списка папок

[править] Метод
umail.get_folders

Запросы также кэшируются раз в 3 минуты.

[править] Параметры
  • sid - идентификатор сессии.
[править] Ответ
  • folders - список папок, состоящий из идентификатора и названия (оставлена для совместимости);
  • folders2 - список папок состоящий из идентификатора, названия и общего количества писем.

[править] Получение писем

[править] Метод
umail.get
[править] Параметры
  • sid - идентификатор сессии;
  • [folder] - идентификатор папки (по умолчанию - Входящие);
  • [unread] - признак прочтённости:
0 - (по умолчанию) все,
1 - не прочтённые;
  • [from] - параметр начала выборки;
  • [limit] - количество выбираемых писем (по умолчанию - максимально - 100);
  • [umailid] - выборка писем по идентификатору;
  • [fields] - список полей через ",", которые необходимо получить (по умолчанию - все поля);
  • [unset] - список полей через ",", которые не должны быть в выводе метода.

Папка Входящие имеет идентификатор 1, Отправленные - 2, Удалённые - 3. Это стандартные папки сообщений, поэтому они доступны, даже если информация об их наличии не выводится методом umail.get_folders.

[править] Ответ
  • count - всего писем, соответствующих параметрам;
  • umail - набор писем:
umailid - идентификатор письма,
from_userid - идентификатор отправителя,
from_username - логин отправителя,
dateline - дата-время отправки письма,
read - флаг прочтения,
no_smilies - флаг запрета конвертации текстовых смайлов,
title - тема письма,
message_html - текст письма.

[править] Отправка писем

[править] Метод
umail.send
[править] Параметры
  • sid - идентификатор сессии;
  • [userid] - идентификатор получателя;
  • [username] - логин получателя;
  • [title] - тема письма;
  • message - текст письма;
  • [save_copy] - сохранить отправленно письмо в папке "Отправленные";
  • [need_receipt] - получить уведомление о прочтении.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Удаление писем

[править] Метод
umail.delete
[править] Параметры
  • sid - идентификатор сессии;
  • umailid - идентификаторы удаляемых сообщений.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Отметить как прочитанные

[править] Метод
umail.read
[править] Параметры
  • sid - идентификатор сессии;
  • umailid - идентификаторы сообщений.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Снять пометку о прочтении

[править] Метод
umail.unread
[править] Параметры
  • sid - идентификатор сессии;
  • umailid - идентификаторы сообщений.
[править] Ответ
  • message - сообщение для пользователя об успешности выполнения действия.

[править] Прочее

[править] Получение тем по идентификаторам

[править] Метод
tags.get

Список идентификаторов тем можно передавать в поле tagid:

  • как отдельно: tagid=1
  • так и в виде массива: tagid[]=2&tagid[]=3&...
[править] Параметры
  • sid - идентификатор сессии;
  • tagid - идентификаторы тем (не более 100 за запрос).
[править] Ответ
  • tags - темы с идентификаторами.

[править] Получение аватаров пользователя

[править] Метод
user.getavatar 
[править] Описание

Метод работает, только если в настройках установлено отображение аватарок.

[править] Параметры
  • sid - идентификатор сессии;
  • [avatarid] - идентификатор аватара.
[править] Ответ
  • count - количество аватаров;
  • avatar - набор аватаров:
avatarid - идентификатор аватара;
width - ширина;
height - высота;
uri - ссылка относительно http://static.diary.ru.
Личные инструменты