Интерфейс программирования приложений (API)

Зачем всё это?

• Области применения

  Области применения API Бобра многогранны. К примеру, с помощью открытого API американской социальной сети facebook любителями были созданы десятки тысяч дополнений. На странице http://www.facebook.com/apps/ можно изучить реализованные дополнения для facebook.

  Аналогично с помощью API Бобра можно реализовать внешние приложения или дополнения для браузера (например, тулбар со встроенным синхронизатором закладок для браузера), интеграцию функционала закладок в другие социальные сети (например, с использованием API вконтакте.ру), а также различные виджеты для вебсайтов и блогов (например, список свежих закладок пользователя в ЖЖ). Наверняка, у вас возникли собственные интересные идеи. Сообщите нам ваши мысли, мы с удовольствием вам поможем в реализации ваших идей.

• С чего начать?

  Для начала необходимо определиться, какое приложение Вы хотите реализовать на базе функциональности БобрДобр. Затем сделайте анализ, не существует ли уже похожее решение в Интернете. Если Вы придумали нечто новое, удобное и востребованное, напишите об этом пользователю spuntik. Мы изучим Ваши предложения и дадим вам в ответ Ваш индивидуальный ключ для использования нашего API.

Как это юзать?

• Формирование запросов

  Обращение к API осуществляется вызовом урл http://bobrdobr.ru/services/rest/?method=XXX&api_key=YYY¶m1=value1¶m2=value2&api_sig=ZZZ

  Где параметры означают следующее:

  [method] Вызываемый метод API. Список всех возможных методов приведён ниже

  [api_key] Индивидуальный ключ вашего приложения

  [api_sig] Подпись запроса

  [param1], [param2] Параметры, передаваемые вызываемому методу

  [value1], [value2] Значения параметров

  Формирование подписи api_sig происходит следующим образом:

  Сортируем передаваемые параметры по алфавиту (параметр method необходимо учитывать). Например, параметры foo=1, bar=2, baz=3 после сортировки выглядят так bar=2, baz=3, foo=1

  Совмещаем секретный ключ, названия и значения параметров в один стринг. Среди параметров необходимо учитывать параметр api_key, например SECRETbar2baz3foo1

  Подсчитываем md5-хэш данного стринга

  Переводим подсчитанный md5-хэш в шестнадцатиричный стринг. Например, api_sig=1f3870be274f6c49b3e31a0c6728957f

• Формат ответа

  Ответ имеет формат REST. REST это простой xml формат.

  Стандартный ответ выглядит следующим образом:

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <rsp stat="ok">
  3. [xml-payload-here]
  4. </rsp>

  Ниже пример ответа метода test.echo

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <rsp stat="ok">
  3.   <method>test.echo</method>
  4.   <format>rest</format>
  5.   <foo>bar</foo>
  6.   <api_key>6c4fd6c70ebe1c65b98646acd3a25b32</api_key>
  7. </rsp>

• Пояснение ошибок системы

  При возникновении ошибки система возвращает следующий ответ:

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <rsp stat="fail">
  3.   <err code="[error-code]" msg="[error-message]" />
  4. </rsp>

  96: Неверная подпись (переданная подпись не действительна)

  97: Подпись отсутствует (запрос требует наличие подписи)

  98: Авторизация не удалась или неверный токен (токен авторизации или пароль неверны)

  99: Пользователь не авторизован или не имеет необходимые права доступа (для вызова метода требуется авторизованный пользователь)

  100: Неверный ключ (переданный ключ не действителен)

  105: Сервис временно недоступен

  111: Формат "xxx" не найден (запрошенный формат ответа не найден)

  112: Метод "xxx" не найден (запрошенный метод не найден)

• Где добыть ключи?

  Для того, чтобы использовать интерфейс, Вам необходимо получить специальный ключ для Вашего приложения. Ключи мы выдаём по индивидуальному запросу. Для этого напишите личное сообщение с запросом на получение ключа для API и описанием Ваших планов использования ключа пользователю spuntik.

Авторизация

• Как она работает?

  Авторизация необходима для работы с закладками авторизованного пользователя. Существует два способа для авторизации на БобрДобр через API:

  1. Самый простой метод авторизации возможен за счёт использования куки авторизации БобрДобр, который передаётся браузеру после успешной авторизации на сайте. Этот метод подходит для веб-приложений, которые в состоянии при каждом запросе к API передавать куки авторизации БобрДобр.

  2. Второй метод подходит для приложений, которые не могут при каждом запросе к API передавать куки авторизации браузера. Это могут быть приложения, которые, например, работают вне браузера или на внешнем домене. В таких случаях приложение должно сделать запрос по адресу http://bobrdobr.ru/service/auth и передать в запросе auth_key и auth_sig. В ответ на этот запрос БобрДобр вызывает указанный при регистрации ключа callback url и передаёт ему токен авторизации. Если, например, callback url является http://test.com/auth.php, то API вызовет http://test.com/auth.php?auth_token=d56e4fdc208ca53e13bde22c7147f7f7, где d56e4fdc208ca53e13bde22c7147f7f7 токен авторизации.

     Токен авторизации имеет срок годности 60 минут. Для продления срока годности токена необходимо вызвать метод auth.getToken.

• Обновление токена авторизации

  Обновляет срок годности токена авторизации

  название метода:

  auth.getToken

  возможные параметры:

  auth_token=vvvv (обязательный) (токен авторизации)

• Проверка токена авторизации

  Проверяет валидность токена авторизации.

  название метода:

  auth.checkToken

  возможные параметры:

  auth_token=vvvv (обязательный) (токен авторизации)

Работа с моими закладками

• Вызов списка моих закладок

  Возвращает закладки пользователя в соответствии с установленным фильтром. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.getBookmarks

  возможные параметры:

  timestamp=xxxx (закладки, изменённые после указанного времени) количество секунд после 1ого января 1970 GMT

  tags=xx,yy,zz (закладки, содержащие перечисленные метки)

  private=true/false (опубликованные или закрытые закладки)

  auth_token=vvvv (токен авторизации)

  возможные ошибки:

  1: неверные формат параметра timestamp

  ответ:

  список с найденными закладками

• Вызов списка моих меток

  Возвращает список меток в соответствии с установленным фильтром. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.getTags

  возможные параметры:

  tags=xx,yy,zz (возвращаются метки, являющиеся уточнительными для перечисленных в параметре)

  auth_token=vvvv (токен авторизации)

  ответ:

  список с метками

• Вызов списка моих групп

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

  название метода:

  userpages.getGroups

  ответ:

  список с группами

• Добавление новой закладки

  Добавляет новую закладку. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.addBookmark

  возможные параметры:

  url=xxxx (обязательный) (урл закладки)

  title=zzzz (обязательный) (название закладки)

  description=yyyyy (описание закладки)

  tags=xx,yy,zz (обязательный) (метки закладки, перечисленные через запятую)

  private=true/false (закрытая или опубликованная закладка)

  auth_token=vvvv (токен авторизации)

  возможные ошибки:

  1: не удалось добавить закладку, ошибка в параметрах

  ответ:

  добавленная закладка

• Редактирование существующей закладки

  Изменяет уже существующую закладку пользователя. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.editBookmark

  возможные параметры:

  bookmark_id=xxxx (обязательный) (идентификатор закладки, которую необходимо изменить)

  title=zzzz (обязательный) (название закладки)

  description=yyyyy (описание закладки)

  tags=xx,yy,zz (обязательный) (метки закладки, перечисленные через запятую)

  private=true/false (закрытая или опубликованная закладка)

  auth_token=vvvv (токен авторизации)

  возможные ошибки:

  1: закладка не найдена

  2: нет прав доступа к закладке

  3: не удалось изменить закладку, ошибка в параметрах

  ответ:

  изменённая закладка

• Удаление закладки

  Удаляет закладку пользователя. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.removeBookmark

  возможные параметры:

  bookmark_id=xxxx (обязательный) (идентификатор закладки, которую необходимо изменить)

  auth_token=vvvv (токен авторизации)

  возможные ошибки:

  1: закладка не найдена

  2: нет прав доступа к закладке

• Добавление закладки в группу

  Возвращает закладки пользователя в соответствии с установленным фильтром. Для вызова этого метода пользователь должен быть авторизован.

  название метода:

  userpages.addBookmarkGroup

  возможные параметры:

  bookmark_id=xxxx (обязательный) (идентификатор закладки, которую необходимо добавить в группу)

  group_id=xxxx (обязательный) (идентификатор группы, в которую необходимо добавить закладку)

  auth_token=vvvv (токен авторизации)

  возможные ошибки:

  1: закладка не найдена

  2: нет прав доступа к закладке

  3: группа не найдена

  4: закладка уже существует в указанной группе

Работа с закладками других пользователей

• Вызов списка закладок пользователя

  Возвращает 100 закладок указанного пользователя в соответствии с установленным фильтром.

  название метода:

  people.getBookmarks

  возможные параметры:

  tags=xx,yy,zz (закладки, содержащие перечисленные метки)

  username=xxxxx (обязательный) (название пользователя)

  возможные ошибки:

  1: пользователь не найден

  ответ:

  список с найденными закладками пользователя

• Вызов списка меток пользователя

  Возвращает 100 самых потребляемых меток указанного пользователя в соответствии с установленным фильтром.

  название метода:

  people.getTags

  возможные параметры:

  tags=xx,yy,zz (возвращаются метки, являющиеся уточнительными для перечисленных в параметре)

  username=xxxxx (обязательный) (название пользователя)

  ответ:

  список с метками указанного пользователя

• Вызов списка групп пользователя

  Возвращает список групп, в которых пользователь является членом.

  название метода:

  people.getGroups

  возможные параметры:

  username=xxxxx (обязательный) (название пользователя)

  ответ:

  список с группами указанного пользователя

• Вызов списка любимых авторов пользователя

  Возвращает список любимых авторов пользователя.

  название метода:

  people.getFriends

  возможные параметры:

  username=xxxxx (обязательный) (название пользователя)

  ответ:

  список с любимыми авторами указанного пользователя

• Поиск пользователей

  Возвращает первые 100 найденных пользователями.

  название метода:

  people.search

  возможные параметры:

  text=xxxxx (обязательный) (поисковая фраза)

  возможные ошибки:

  1: не указана поисковая фраза

  ответ:

  список с пользователями, найденными поиском

Работа с группами

• Вызов списка группы рубрики

  Возвращает 100 самых больших групп указанной рубрики.

  название метода:

  groups.browse

  возможные параметры:

  cat_id=xxxxx (обязательный) (идентификатор рубрики групп)

  возможные ошибки:

  1: рубрика не найдена

  ответ:

  список с найденными группами указанной рубрики

• Вызов списка закладок группы

  Возвращает 100 закладок указанной группы в соответствии с установленным фильтром.

  название метода:

  groups.getBookmarks

  возможные параметры:

  tags=xx,yy,zz (закладки, содержащие перечисленные метки)

  group_id=xxxxx (обязательный) (идентификатор группы)

  возможные ошибки:

  1: группа не найдена

  2: группы закрыта

  ответ:

  список с найденными закладками указанной группы

• Вызов списка меток группы

  Возвращает 100 самых потребляемых меток указанной группы в соответствии с установленным фильтром.

  название метода:

  groups.getTags

  возможные параметры:

  tags=xx,yy,zz (возвращаются метки, являющиеся уточнительными для перечисленных в параметре)

  group_id=xxxxx (обязательный) (идентификатор группы)

  возможные ошибки:

  1: группа не найдена

  2: группы закрыта

  ответ:

  список с метками указанной группы

• Вызов списка участников группы

  Возвращает список участников группы.

  название метода:

  groups.getMembers

  возможные параметры:

  group_id=xxxxx (обязательный) (идентификатор группы)

  возможные ошибки:

  1: группа не найдена

  2: группы закрыта

  ответ:

  список с участниками указанной группы

• Поиск групп

  Возвращает первые 100 найденных групп.

  название метода:

  groups.search

  возможные параметры:

  text=xxxxx (обязательный) (поисковая фраза)

  возможные ошибки:

  1: не указана поисковая фраза

  ответ:

  список с группами, найденными поиском

Работа с общими закладками

• Вызов списка закладок с метками

  Возвращает 100 самых свежих закладок с указанными метками.

  название метода:

  public.getBookmarks

  возможные параметры:

  tags=xx,yy,zz (закладки, содержащие перечисленные метки)

  ответ:

  список с найденными закладками

• Вызов списка уточняющих меток

  Возвращает 100 самых потребляемых уточняющих меток для указанных меток.

  название метода:

  public.getTags

  возможные параметры:

  tags=xx,yy,zz (возвращаются метки, являющиеся уточнительными для перечисленных в параметре)

  ответ:

  список уточняющих меток

• Вызов списка пользователей с метками

  Возвращает список с пользователями, которые используют указанные метки.

  название метода:

  public.getUsersByTag

  возможные параметры:

  tags=xx,yy,zz (обязательный) (метки пользователей)

  ответ:

  список с пользователями, использующих указанные метки

• Суперпоиск закладок

  Возвращает 100 самых свежих закладок.

  название метода:

  public.search

  возможные параметры:

  text=xxxxx (обязательный) (поисковая фраза)

  возможные ошибки:

  1: не указана поисковая фраза

  ответ:

  список с закладками, найденными поиском

Проверка связи

• Эхо

  Возвращает переданные методу список параметров обратно.

  название метода:

  test.echo

• Проверка авторизации

  Проверяет авторизацию и возвращает имя авторизованного пользователя.

  название метода:

  test.login

  возможные параметры:

  auth_token=vvvv (токен авторизации)

  ответ:

  имя авторизованного пользователя

• Нулевой тест

  Нулевой тест

  название метода:

  test.null

Формат ответов

• Список закладок

  1. <bookmarklist>
  2.     <bookmark id="xxx" modified="yyyy" private="true/false" username="zzzz">
  3.         <title>bookmark title</title>
  4.         <url>bookmark url</url>
  5.         <description>bookmark description</description>
  6.         <tags>
  7.             <tag>first tag</tag>
  8.             <tag>second tag</tag>
  9.         </tags>
  10.     </bookmark>
  11. </bookmarklist>

• Список меток

  1. <taglist>
  2.     <tag weight="xxx">yyyy</tag>
  3. </taglist>

• Список групп

  1. <grouplist >
  2.     <group id="xxx" private="true/false" created="ccc" bookmarkcount="yyy" membercount="zzz">
  3.         <title>group title</title>
  4.         <description>group description</description>
  5.         <categories>
  6.             <cat id="xx">categorie name</tag>
  7.             <cat id="yy">categorie name</tag>
  8.             <cat id="zz">categorie name</tag>
  9.         </categories>
  10.     </group>
  11. </grouplist>

• Список членов группы

  1. <memberlist>
  2.     <user username="xxx" role="founder/moderator/member" />
  3. </memberlist>

• Список пользователей

  1. <peoplelist>
  2.     <user username="xxx" bookmarkcount="yyy" />
  3. </peoplelist>