Платформа@Mail.Ru предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в Mail.Ru. Одним из способов такого взаимодействия вляется использование REST API.
REST API определяет набор функций, к которым разработчики могут совершать запросы и получать ответы. Взаимодействие происходит по протоколу HTTP. Преимуществом такого подхода является широкое распространение протокола HTTP, поэтому REST API можно использовать практически из любого языка программирования.
REST API предназначено, в основном, для запросов с внешних серверов к серверам Mail.Ru. Для запросов с веб-клиентов — клиентской части социального приложения или от сайта — существуют JS API и Flash-библиотека, которые более удобны и просты в использовании.
Все вызовы методов API — это GET или POST HTTP-запросы к URL http://www.appsmail.ru/platform/api с некоторым набором параметров. Вы выбираете в документации нужный метод, например, users.getInforest, формируете запрос согласно документации метода, и осуществляете этот запрос. В ответ на запрос вы получаете его результат, который также описан в документации каждой функции. Кодировка результата — UTF-8.
Например, на PHP для осуществления такого запроса можно использовать cURL, на Perl — LWP::Simple, на Python — urllib, использовать cURL из командной строки и даже просто ваш браузер.
Обратите внимание на готовые библиотеки, возможно, для вашего языка программирования уже существует реализация REST API.
Данные запроса могут передаваться в виде query-строки (после знака ?) при использовании метода GET, либо в теле POST-запроса. Помните, что в случае GET-запроса, параметры должны быть закодированы с помощью URL encoding.
На данный момент, API не делает различий между GET- и POST-запросами. Тем не менее, помните, что существует ограничение на длину URL запроса — 2048 символов. Поэтому мы рекомендуем вам выполнять запросы на получение информации с помощью метода GET (они обычно легко умещаются в ограничение), а запросы на изменение данных — загрузку фотографии, новый пост в «Что нового» или гостевую книгу — с помощью метода POST. Так вы не будете ограничены длиной запроса, кроме того, такое использование больше соответствует спецификации протокола HTTP.
В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой функции в ее документации определены дополнительные параметры, нужные только для этой функции. Текстовые значения параметров должны быть переданы в кодировке UTF-8. Одинаковые для всех функций параметры перечислены ниже.
| Имя | Тип | Описание |
|---|---|---|
| method | string | название вызываемого метода, например, users.getInfo; обязательный параметр |
| app_id | int | идентификатор приложения; обязательный параметр |
| sig | string | подпись запроса; обязательный параметр |
| session_key | string | сессия текущего пользователя |
| uid | uint64 | идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key |
| secure | bool | флаг, обозначающий, что запрос идет по защищенной схеме «сервер-сервер»; возможные значения: 1 или 0; по-умолчанию 0 |
| format | string | формат выдачи ответа API; возможные значения: xml или json; по-умолчанию json |
Порядок следования параметров в запросе значения не имеет, порядок параметров важен только при расчете подписи.
Идентификатор приложения app_id уникален для каждого приложения или сайта и его можно узнать в разделе Мои разработки для приложений и Мои сайты для сайтов.
Флаг secure и подпись sig расчитываются в зависимости от схемы запроса (см. ниже).
Параметры session_key и uid отвечают за авторизацию, то есть от лица какого пользователя происходит запрос. В зависимости от этого одна и та же функция в одном и том же приложении может возвращать немного разные результаты, например, когда один пользователь имеет доступ к каким-то закрытым данным, а другой нет. session_key используется для выполнения запросов по схеме «клиент-сервер» (см. ниже), а uid — по схеме «сервер-сервер».
Сессия (session_key) получается при каждом новом сеансе работы пользователя с вашим приложением или сайтом. При последующих заходах того же пользователя это значение будет другим, поэтому сохранять его не надо. Значение session_key вы получаете в зависимости от того, как вы используете REST API. Если вы используете API в клиенте социального приложения, session_key приходит вам в параметрах запроса (см. как разрабатывать социальные приложения), если вы интегрируете API для сайтов, сессия получается в процессе логина (см. как интегрировать сайты). В любом случае, после получения session_key, вы можете передать это значение на сервер чтобы осуществлять вызовы функций API с вашего сервера от лица текущего пользователя.
Значение uid вы можете сохранять в вашей базе зарегистрированных пользователей и использовать в тех случаях, когда пользователь не использует выше приложение, и, соответственно, сессия не доступна. Например, когда вы отправляете пользователям уведомления с помощью функции notifications.sendrest.
Мы рекомендем вам всегда использовать session_key, когда это возможно, потому что в дальнейшем он может требоваться для некоторых возможностей API. Используйте uid только когда вы выполняете запросы пока пользователь не использует ваше приложение или сайт.
Чтобы удостовериться, что запрос отправлен действительно вами, а не злоумышленниками от лица вашего приложения, все запросы к REST API должны быть подписаны. Подпись может вычисляться по двум схемам: клиент-сервер и сервер-сервер. Результат расчета подписи вы должны передать в параметре sig, Платформа проверит подпись и выполнит запрос только если подпись правильная.
Схема клиент-сервер предназначена для случаев, когда REST API используется из клиента социального приложения, клиентского кода сайта или отдельного мобильного или desktop-приложения.
Если вы хотите использовать схему клиент-сервер, то передайте в параметрах запроса secure=0 и расчитайте sig по следующему алгоритму:
sig = md5(uid + params + private_key)
Значение params — это конкатенация пар «имя=значение» отсортированных в алфавитом порядке по «имя», где «имя» — это название параметра, передаваемого в функцию API, «значение» — значение параметра. Разделитель в конкатенации не используется. Параметр sig при расчете подписи не учитывается, все остальные параметры запроса должны учитываться при расчете.
Значение uid — идентификатор текущего пользователя приложения. Значение private_key вы можете взять из настроек приложения.
Например,
Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме клиент-сервер:
function sign_client_server(array $request_params, $uid, $private_key) {
ksort($request_params);
$params = '';
foreach ($request_params as $key => $value) {
$params .= "$key=$value";
}
return md5($uid . $params . $private_key);
}
Вы можете встраивать ключ private_key в клиенты приложений и в публично доступный код сайта. Таким образом, целеустремленные злоумышленники теоретически могут подделать запросы от вашего приложения, подписанные по схеме клиент-сервер. Из-за этого некоторые запросы можно выполнять только по схеме сервер-сервер.
Схема сервер-сервер является более надежной. Используйте ее для критичных к безопасности запросов.
Некоторые запросы, которые подразумевают согласие пользователя, можно выполнить только по схеме клиент-сервер. В случае невозможности выполнения запроса по схеме сервер-сервер, вам вернется соответствующая ошибка.
Схема сервер-сервер использует отдельный ключ secret_key, который мы настоятельно рекомендуем вам хранить только на ваших серверах и использовать только при запросах с них к серверам Платформы.
Когда вы хотите использовать схему сервер-сервер, вы должны передать в параметрах запроса параметр secure=1 и расчитать значение параметра sig следующим образом:
sig = md5(params + secret_key)
Например,
Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме сервер-сервер:
function sign_server_server(array $request_params, $secret_key) {
ksort($request_params);
$params = '';
foreach ($request_params as $key => $value) {
$params .= "$key=$value";
}
return md5($params . $secret_key);
}
Безопасность схемы сервер-сервер основывается на том, что secret_key знаете только вы и Платформа. Поэтому никогда не раскрывайте его третьим лицам. Если у вас возникли сомнения в безопасности secret_key, перегенерите его в настройках приложения.
Установка приложения (первая авторизация) дает приложению возможность получать информацию о пользователе, его друзьях, фотографиях, музыке. То есть пользоваться функциями users.getInforest, friends.getrest, photos.getrest, audios.getrest и подобными. Также приложение может отсылать пользователю уведомления с помощью функции notifications.sendrest. Установка в большом и мобильном мире производится автоматически Платформой. Для установки standalone-приложений необходимо использовать OAuth-авторизацию для standalone-приложений. Для установки (коннекта) внешнего сайта надо пользоваться либо OAuth-авторизацией для сайтов, либо функцией connect.loginjs.
Для standalone-приложений и сайтов запросить привилегии можно либо через параметр scope OAuth-авторизации, либо в параметрах функции connect.loginjs.
Привилегии распространяются только на функции REST API. Функции JS API не зависят от привилегий и при попытке записи в Мой Мир всегда показывают пользователю диалог с запросом подтверждения действия. Вы можете выбирать просить ли у пользователя привилегии и использовать REST API или использовать диалоги из JS API.
Не все привилегии доступны во всех контекстах:
| Название привилегии | Смысл | Функции | Мой Мир | Мобильный Мир | Standalone-приложения | Сайты |
|---|---|---|---|---|---|---|
| photos | приложение может загружать фотографии | photos.uploadrest, photos.createAlbumrest | нет | нет | есть | есть |
| guestbook | приложение может добавлять записи в гостевые книги пользователей | guestbook.postrest | нет | нет | есть | есть |
| stream | приложение может добавлять записи в ленту «Что нового» пользователя | stream.postrest | нет | нет | есть | есть |
| messages | приложение имеет доступ к личным сообщениям пользователя | messages.getThreadrest, messages.getThreadsListrest, messages.postrest, messages.getUnreadCountrest | нет | нет | есть | есть |
| events | приложение имеет доступ к событиям пользователя в Моем Мире | events.getUnreadCountrest | нет | нет | есть | есть |