БобрДобр

  • Храните закладки в интернете
  • Используйте теги для систематизации
  • Обменивайтесь ссылками с друзьями
  • Создавайте группы по любимым темам

Сверхбыстрая регистрация

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

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

БобрДобр — это сервис для работы с избранными закладками в Интернете. Он дает возможность пользователям хранить и систематизировать закладки, делиться и обмениваться ими с друзьями или знакомыми, создавать сообщества по темам и интересами, собирать в рамках этих сообществ ссылки вместе с другими их участниками. Кроме того сервис предоставляет разные возможности показать другим лучшие ссылки, которые вам удалось найти по той или иной теме.

С помощью описанного на этой странице API вы сможете создать приложения на базе функциональности сервиса социальных закладок БобрДобр и интегрировать её, а так-же контент БобрДобр в ваши веб-приложения и веб-сайты. Области применения 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>