Это пока что beta-версия Nirvana API, мы не гарантируем 100% работоспособности. Возможны изменения. Если вам нужно больше функционала и для вашего приложения необходима какая-либо функция или api, которой нет в списке, то напишите на блоге разработчиков свой вопрос http://nirvana.fm/~developers.


Типы данных
В API используется только 1 тип данных - это текст в кодировке utf-8. Даже числа записываются текстом, а не двоичным представлением.
Однако для удобства мы опишем типы данных нескольких полей, чтобы вы в своей программе могли проверять допустимые значения данных.

Поля "user_id", "offset", "after_id", "time_unix" и "id" в структуре <messages> - unsigned integer 64-bit (uint64_t аналог в языке си), поэтому учитывайте это при работе с api.
Если вы разрабатываете приложение для платформы не поддерживающей 64-битные целые числа, то храните эти значения как строки или используйте специальные модули для эмуляции 64-битных чисел.

Поле "count" - во всех запросах это целое ненулевое число, как правило <= 1000, а для сообщений <= 100.

Поле "sid" и "code_id" - длина всегда 50 символов, допустимые символы [A-Za-z0-9-_]{50}.
Поле "code" - длина всегда "5" символов, допустимы только цифры [0-9]{5}.

Поле "time" - содержит время в текстовом формате, в отличие от "time_unix".
Получение app_id и api_secret и создание приложения
Чтобы создать приложение зайдите в меню "Мои сайты и приложения", нажмите на кнопку "Создать сайт или приложение", укажите название вашего приложения и тип "exe-программа или приложение для android или iphone".
Затем нажмите "редактировать" и укажите описание вашего приложения, если это приложение для android или iphone, то укажите ссылку на маркет где размещается ваше приложение.
Если вы просто тестируете api, то так и напишите в описнии "тестирую api". Описание приложения нужно указывать, чтобы ваше приложение мог проверить и протестировать администратор сайта.

Затем в списке приложений появится ваше созданное приложение и там будут указаны переменные app_id и api_secret, которые вам понадобятся для вызова api.


Вызов API
Для формата XML, api вызываются так http://nirvana.fm/api/{method}?app_id=укажите_id_вашего_приложения&api_secret=укажите_api_secret_вашего_приложения&sid={идентификатор_сессии_пользователя}&format=xml

Для Javascript в формате JSON, api вызываются так http://nirvana.fm/api/{method}?app_id=укажите_id_вашего_приложения&api_secret=укажите_api_secret_вашего_приложения&sid={идентификатор_сессии_пользователя}&format=json&callback={имя_callback_функции}

Параметры:
method - имя вызываемого api-метода. Методы перед названием которых стоит "_" как правило тестовые и их реализация может меняться со временем. Методы без "_", уже протестированные и готовые к работе.
app_id и api_secret - переменные, полученные вами при создании приложения
sid - идентификатор сессии пользователя, полученный вами из метода "auth", он используется не во всех методах, а только в тех, которые требуют авторизации. sid не обязательно передавать в параметрах, если у вас включены cookie, то после авторизации он туда запишется и будет браться из cookie.
format - xml или json
callback - имя callback-функции в javascript, которая будет вызвана после вызова api. Этой функции в качестве параметра передаётся хэш с запрашиваемыми данными. Если callback не указывать, то просто вернётся хэш с данными без вызова функции.

параметры функции передаются через GET или POST переменные.

В http-запросе должно присутствовать поле Accept-Language, для указания языка на котором будут выдаваться ответы, например так "Accept-Language: ru-RU" или "Accept-Language: en-US". Список доступных языков можно посмотреть в меню выбора языка сайта.


Как будет выглядеть результат?

<?xml version="1.0" encoding="UTF-8"?>
<result>
...
</result>

Для JSON:
MyCallbackFunc({ result: { ... } });


Как будет выглядеть результат в случае ошибки?

<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>код ошибки</code>
<text>расшифровка ошибки</text>
</error>

Для JSON:
MyCallbackFunc({ error: { code: "код ошибки", text: "расшифровка ошибки" } });


Коды ошибок:
TRY_AGAIN - она же Bad gateway 502, означает что сервис временно недоступен (возможно из-за большой нагрузки) и нужно повторить ваш запрос через 10-15 секунд. Ошибка возникает достаточно редко, но всё же стоит её учитывать.
NOT_LOGINED - пользователь не залогинен
USER_DELETED - пользователь удалился
WRONG_CODE - неверно введён код защиты (капча)
EMPTY_MESSAGE - пустое сообщение
IGNORE_LIST_I - вы добавили пользователя в игнор лист, поэтому сообщение не может быть отправлено
IGNORE_LIST_ME - пользователь добавил вас в игнор лист, поэтому сообщение не может быть отправлено
DISK_LOCK - редкая ошибка, но всё же иногда может быть. Означает, что производятся профилактические работы с диском на котором хранятся сообщения и контакты пользователя.
BAN_PM - бан на отправку личных сообщений.


http://nirvana.fm/api/auth - авторизация
Параметры:
app_id и api_secret
success_url - ссылка на которую будет переадресация в случае успешной авторизации. Можно использовать псевдо-url, например "JavaScript://?status=ok", если вы в своей программе ловите запросы браузера.

Как использовать?
Вызов этой функции отличается от остальных. Вам нужно встроить в своё приложение компонент "Веб-браузер", в разных средах разработки он может называться по разному, например в android он называется "WebView".
Для удобства пользователей рекомендуем сохранять cookie у компонента "WebView" полученные от api, это позволит пользователю не вводить при каждом запуске свой логин и пароль, а пользоваться уже сохранённой сессией.

Результат:
Если пользовтель не залогинен, то отобразится html-форма для ввода логина и пароля.
В случае неверного ввода логина и пароля пользователю снова отобразится html-форма для ввода логина и пароля и покажется сообщение об ошибке.
Если авторизация прошла успешно, то произойдёт переадресация на success_url, к которому будет добавлен параметр "sid" (идентификатор сессии пользователя, который вам потребуется для вызова api).

Компонент WebView позволяет отлавливать изменение url, и если произошла переадресация на заданный вами псевдо-url "JavaScript://?status=ok&sid=идентификатор_сессии", то это значит, что авторизация прошла успешно.

webView.setWebViewClient(new WebViewClient() {
        @Override
        public boolean shouldOverrideUrlLoading(WebView view, String url) {
                if (url.indexOf("JavaScript://?status=ok") == 0) {
                        System.out.println("webView success url = " + url);

                        // успешная авторизация
                        // тут нужно вытащить параметр sid из url для дальнейшего использования

                        return false;
                }
                return true;
        }
});

Мы тестировали api только на платформе android, но скорее всего на других платформах есть похожий функционал. Если есть вопросы или замечания по реализации, то зайдите на блог разработчиков и создайте тему с вашим вопросом.


http://nirvana.fm/api/logout - разлогинить пользователя
Параметры:
app_id, api_secret и sid

Результат:
code=OK


Структура <user> - используется в api, которые возрващают информацию о пользователях
Параметры, влияющие на результат:
foto_big=1 - если добавить этот параметр, то фото пользователей будут размера 200x280, без него 80x110.

<user>
        is_my=1 - если есть этот параметр, то значит это ваша анкета, на остальных анкетах этого поля не будет.
        user_id - номер анкеты
        name - имя пользователя
        sex - пол (возможные значения "f" - женский, "m" - мужской)
        sex_icon - ссылка на значёк пола пользователя, используемый на сайте
        birthday - дата рождения в формате dd.mm.yy
        age - возраст
        city - город
        about_me - поле "обо мне"
        onsite - возможные значения "nevidimka" - включен режим невидимки, "online" - сейчас на сайте или дата-время когда последний раз был на сайте.
        foto - url-ссылка на главное фото.
        fotos_count - количество фото
</user>

если аккаунт пользователя удалён, то структура будет выглядеть так:
<user>
        user_id - номер анкеты
        deleted=1
</user>


http://nirvana.fm/api/pm/contacts - получение списка папок и контактов
Параметры:
app_id, api_secret и sid
folder_id - идентификатор папки для которой получаем список контактов, если этот параметр не указан, то контакты выдаются для default-папки, обычно это "Общая папка", если она не переименовывалась. Также может принимать значение folder_id=trash для контактов из корзины.
offset - позиция, начиная с которой будет выдаваться список контактов в папке, если параметр не указан, то он считается равным 0.
limit - максимальное количество контактов, которые будут выданы начиная с позиции offset (по умолчанию =10). if (limit < 10) limit = 10; if (limit > 1000) limit = 1000;
foto_big - см описание структуры <user>
filter - если этот параметр указан, то к списку контактов применяется фильтр, возможные значения: new - только с новыми сообщениями, online - только онлайн.

Результат:
filter, offset, limit - содержат теже значения, что и на входе
folders - список папок, в формате:
<folder>
        id - идентификатор папки.
        icon - url-ссылка на значок папки.
        name - название папки.
        c_count - количество контактов в папке.
        c_new - количество новых контактов в папке (на сайте это число красным выделяется).
        c_count_with_filter - количество контактов найденных с учётом фильтра, может использоваться для постраничной разбивки результата, если оно больше limit. Если фильтр не применялся, то это поле содержит такое же значение как и c_count.
        m_count - суммарное количество сообщений в контактах в папке.
        m_new - суммарное количество новых сообщений в контактах в папке (на сайте это число выделяется красным).
        contacts - список контактов в папке, устанавливается только для одной папки (folder_id), в остальных этого поля не будет.
        <contact>
                count - количество сообщений.
                count_new - количество новых сообщений.
                user - структура <user> для этого контакта.
        </contact>
</folder>
trash - список контактов в корзине, в формате:
<trash>
        c_count - количество контактов в корзине.
        c_count_with_filter - количество контактов найденных с учётом фильтра, может использоваться для постраничной разбивки результата, если оно больше limit. Если фильтр не применялся, то это поле содержит такое же значение как и c_count.
        contacts - список контактов в корзине, устанавливается только если folder_id=trash.
        <contact>
                count - количество сообщений, поля count_new тут не будет, как только контакт из корзины напишет вам сообщение он сразу же переносится в общую папку.
                user - структура <user> для этого контакта.
        </contact>
</trash>
ban_pm=1 - если это поле установлено, то пользователь получил бан за рассылку спама (как правило от 2 до 7 дней), отправка сообщений работать не будет.


Почему объединили api получения списка папок и контактов в одно?
Потому что в большинстве приложений при отображении списка папок нужно сразу же отобразить список контактов для одной из этих папок и чтобы не делать 2 запроса подряд эти api объединили.

Возвращаемые коды ошибок:
NOT_LOGINED


http://nirvana.fm/api/pm/messages - список сообщений.
Параметры:
app_id, api_secret и sid
user_id - номер анкеты собеседника
offset - позиция, начиная с которой будет выдаваться список сообщений, если параметр не указан, то он считается равным 0.
after_id - вместо "offset" можно указать "after_id" - идентификатор сообщения, после которого будет выдан список, используется для подгрузки предыдущих сообщений (при перелистывании страниц), этот параметр предпочтительнее чем "offset", т.к. он учитывает изменения в переписке с момента последней загрузки страницы.
limit - максимальное количество сообщений, которые будут выданы начиная с позиции offset (по умолчанию =10). if (limit < 10) limit = 10; if (limit > 100) limit = 100;

Результат:

offset или after_id, limit - содержат теже значения, что и на входе
count - количество сообщений, может использоваться для постраничной разбивки результата, если оно больше limit
user - структура <user> для собеседника
messages - список сообщений, в формате:
<message>
        id - идентификатор сообщения
        user_id - номер анкеты отправителя
        time - время отправки сообщения
        time_unix - время отправки сообщения в формате unix по гринвичу (без учёта часового пояса и летнего времени). Используется для отправки событий о новом сообщении и прочитанном сообщении.
        new=1 - если это поле установлено, то сообщение ещё не было прочитано собеседником
        text - текст сообщения в html-формате, где уже преобразованы bb-коды и ссылки в html-код.
        text_raw - текст сообщения в сыром формате, если вы хотите сами по своему парсить bb-коды, ссылки и прочие специальные символы.
</message>
code - если это поле установлено, то требуется отобразить пользователю каптчу перед отправкой сообщения
<code>
        id - идентификатор картинки с кодом, используется для отправки сообщения через api /pm/send_message. 50-ти значный код, состоящий из символов [A-Za-z0-9-_]
        url - ссылка на картинку с кодом, выглядит примерно так http://nirvana.fm/code/{$id}
        width - ширина картинки в пикселях, всегда равно 101.
        height - высота картинки в пикселях, всегда равно 31.
</code>
ignore_list_i=1 - если это поле установлено, то вы занесли этого пользователя в игнор-лист, отправка сообщений работать не будет.
ignore_list_me=1 - если это поле установлено, то этот пользователь занёс вас в игнор-лист, отправка сообщений работать не будет.
ban_pm=1 - если это поле установлено, то пользователь получил бан за рассылку спама (как правило от 2 до 7 дней), отправка сообщений работать не будет.

Возвращаемые коды ошибок:
NOT_LOGINED
USER_DELETED


http://nirvana.fm/api/send_message - отправка сообщения пользователю.
Параметры:
app_id, api_secret и sid
user_id - номер анкеты собеседника.
text - текст сообщения.
если при вызове api /pm/messages выдалось поле code, то необходимо передать 2 параметра code и code_id. Если поля code не было, то не нужно передавать code и code_id.
code - код с каптчи, введённый пользователем, должен состоять из 5 цифр изображённых на каптче.
code_id - идентификатор картинки с кодом, полученный при вызове api /pm/messages.
limit - максимальное количество сообщений, которые будут выданы начиная с позиции 0 (по умолчанию =10). if (limit < 10) limit = 10; if (limit > 100) limit = 100;
Для этого api не используется параметр offset, он считается равным 0, т.к. после отправки сообщения нужно получить последние отправленные, а не откуда-то из середины.

Результат:
limit - содержит тоже значение, что и на входе
count - количество сообщений, может использоваться для постраничной разбивки результата, если оно больше limit
user - структура <user> для собеседника
messages - список сообщений, в формате:
<message>
        user_id - номер анкеты отправителя
        time - время отправки сообщения
        time_unix - время отправки сообщения в формате unix по гринвичу (без учёта часового пояса и летнего времени). Используется для отправки событий о новом сообщении и прочитанном сообщении.
        new=1 - если это поле установлено, то сообщение ещё не было прочитано собеседником
        text - текст сообщения в html-формате, где уже преобразованы bb-коды и ссылки в html-код.
        text_raw - текст сообщения в сыром формате, если вы хотите сами по своему парсить bb-коды, ссылки и прочие специальные символы.
</message>

В отличие от api /pm/messages тут не будет поля code, если код каптчи был введён верно, то после отправки сообщения он больше не будет требоваться.
Также не будет полей ignore_list_i, ignore_list_me и ban_pm, так как вместо них выдаётся ошибка с таким же кодом.

Возвращаемые коды ошибок:
NOT_LOGINED
USER_DELETED
EMPTY_MESSAGE
IGNORE_LIST_I
IGNORE_LIST_ME
BAN_PM
DISK_LOCK
WRONG_CODE
Ошибка с префиксом "E_" - встречается редко, но тоже может быть.


http://nirvana.fm/api/_get_comet - получение событий о новых сообщениях и о статусе "пользователь печатает".
Параметры:
app_id, api_secret и sid

Результат:
user_id - номер анкеты пользователя.
server - имя сервера для comet/websocket запросов (но вместо этого лучше используйте поля comet_listen/comet_send/websocket содержащие готовую ссылку на канал пользователя).
comet_listen - http-ссылка на comet-канал пользователя для получения событий. После отправки запроса вам будет непрерывно приходить html-код, в котором в реальном времени будут приходить события.
comet_send - http-ссылка на comet-канал пользователя для отправки событий. Посылаете POST-запрос на эту ссылку, в качестве post-данных укажите "sender_id|cmd|первый_параметр|второй_параметр|и_так_далее", поля разделяются символом "|", sender_id = номер анкеты отправителя, cmd - название события, далее указываются параметры связанные с этим событием.
websocket - ws-ссылка на websocket-канал пользователя для получения и отправки событий. Формат данных такой же как и для comet.
online - http-ссылка для отправки статуса пользователь онлайн. Посылаете POST-запрос на эту ссылку, в качестве post-данных укажите любые не пустые данные, например "1".
online_send_interval - интервал в секундах, через который можно отправлять статус "онлайн", обычно равен 60 секундам. Вы не должны отправлять статус онлайн чаще, чем указано в этом поле, реже можно.

Возможные значения поле cmd:
pm/typing - собеседник sender_id печатает.
pm/new_message|{last_message_time} - уведомление о новом сообщении, после отправки сообщения пользователю, вы должны отправить это событие. Параметр last_message_time - это время отправки последнего сообщения, это время нужно получить из поля messages.time_unix последнего сообщения из результата комманды _send_message.
pm/message_readed|{last_message_time} - если сообщение, полученное по api _messages имело поле new_message=1, и пользователь его прочёл, то нужно отправить это событие. Параметр last_message_time - это время из поля messages.time_unix последнего сообщения из результата комманды _messages.

Теоретически вы можете добавлять и свои cmd для реализации специфических функций вашего приложения, но они должны именоваться следующим образом: app/id_вашего_приложения/название_события, чтобы не пересекаться с пространством имён стандартных событий.


http://nirvana.fm/api/_search - поиск пользователей, раздел "Люди".
Параметры:
app_id, api_secret и sid
offset - смещение от начала
limit - количество записей в результате
sex - я ищу, 2 - женщину, 1 - мужчину, 0 - всех.
age_from и age_to - возраст от и до, числа от 14 до 255, если будет age_from > age_to, то значения поменяются местами (age_from, age_to) = (age_to, age_from).
s_location - страна/регион/город, но пока не придуман способ красиво передавать данные.
has_foto=1 - искать только с фото
filter - 1 - сейчас на сайте, 2 - новые анкеты, 4 - отображать также анкеты, которые включили ограничение на новые контакты. Значения можно складывать, тогда их действие объединится.
last_online_from и last_online_to - время последнего посещения сайта в днях

Результат:
Последовательность структур <user></user>


http://nirvana.fm/api/_get_users - получение информации о пользователях по номеру анкеты.
Параметры:
app_id, api_secret и sid
ids - список номеров анкет пользователей разделённых запятой. Также помимо номеров анкет можно указать "my", например "123456,my,7689", тогда в списке будет и ваша анкета.

Результат:
Последовательность структур <user></user>


http://nirvana.fm/api/_get_smiles - получение списка смайликов пользователя.
Параметры:
app_id, api_secret и sid
Результат:
<smile>
        id - номер, идентификатор смайлика.
        url - ссылка на смайлик.
        width и height - размеры смайлика.
        code - код для вставки в текст.
</smile>

Если добавить параметр "show=all" то будет выдан полный список всех смайликов, что есть на сайте.

Результат:
<group>
        title - название группы смайликов.
        count - количество смайликов в группе.
        <smile>
                информация о смайлике, как и в предыдущем пункте.
        </smile>
</group>


http://nirvana.fm/api/_get_user_fotos - получение списка фотографий пользователя.
Параметры:
app_id, api_secret и sid
user_id - номер анкеты пользователя

Результат:
<foto>
        id - номер, идентификатор фото.
        url_80x110 - ссылка на фото размера 80x110
        url_200x280 - ссылка на фото размера 200x280
        url_500     - ссылка на большое фото, размеры которого по ширине и высоте не превышают 500.
</foto>


http://nirvana.fm/api/_server_time - узнать какое сейчас время на сервере.
Параметры:
app_id и api_secret

Результат:
time - время
time_unix - время в формате unix по гринвичу (без учёта часового пояса и летнего времени)