Руководство по использованию REST API

Платформа@Mail.Ru предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в Mail.Ru. Одним из способов такого взаимодействия вляется использование REST API.

Что такое REST API

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

REST API предназначено, в основном, для запросов с внешних серверов к серверам Mail.Ru. Для запросов с веб-клиентов — клиентской части социального приложения или от сайта — существуют JS API и Flash-библиотека, которые более удобны и просты в использовании.

Как использовать API

Все вызовы методов API — это GET или POST HTTP-запросы к URL http://www.appsmail.ru/platform/api с некоторым набором параметров. Вы выбираете в документации нужный метод, например, users.getInforest, формируете запрос согласно документации метода, и осуществляете этот запрос. В ответ на запрос вы получаете его результат, который также описан в документации каждой функции. Кодировка результата — UTF-8.

Например, на PHP для осуществления такого запроса можно использовать cURL, на Perl — LWP::Simple, на Python — httplib, использовать 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.

Сессия (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 вы можете взять из настроек приложения.

Например,

Пусть uid=1324730981306483817 и private_key=7815696ecbf1c96e6894b779456d330e

Запрос, который вы хотите выполнить:
http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa

Тогда:
params = app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa
sig = md5(1324730981306483817app_id=423004method=friends.getsession_key=be6ef89965d58e56dec21acb9b62bdaa7815696ecbf1c96e6894b779456d330e)
    = 5073f15c6d5b6ab2fde23ac43332b002

Итоговый запрос:
http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&sig=5073f15c6d5b6ab2fde23ac43332b002

Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме клиент-сервер:

  1. function sign_client_server(array $request_params, $uid, $private_key) {
  2.   ksort($request_params);
  3.   $params = '';
  4.   foreach ($request_params as $key => $value) {
  5.     $params .= "$key=$value";
  6.   }
  7.   return md5($uid . $params . $private_key);
  8. }

Вы можете встраивать ключ private_key в клиенты приложений и в публично доступный код сайта. Таким образом, целеустремленные злоумышленники теоретически могут подделать запросы от вашего приложения, подписанные по схеме клиент-сервер. Из-за этого некоторые запросы можно выполнять только по схеме сервер-сервер.

Сервер-сервер

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

Схема сервер-сервер использует отдельный ключ secret_key, который мы настоятельно рекомендуем вам хранить только на ваших серверах и использовать только при запросах с них к серверам Платформы.

Когда вы хотите использовать схему сервер-сервер, вы должны передать в параметрах запроса параметр secure=1 и расчитать значение параметра sig следующим образом:

  sig = md5(params + secret_key)

Например,

Пусть uid=1324730981306483817 и secret_key=3dad9cbf9baaa0360c0f2ba372d25716

Запрос, который вы хотите выполнить:
http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&secure=1

Тогда:
params = app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa
sig = md5(app_id=423004method=friends.getsecure=1session_key=be6ef89965d58e56dec21acb9b62bdaa3dad9cbf9baaa0360c0f2ba372d25716)
    = 4a05af66f80da18b308fa7e536912bae

Итоговый запрос:
http://www.appsmail.ru/platform/api?method=friends.get&app_id=423004&session_key=be6ef89965d58e56dec21acb9b62bdaa&secure=1&sig=4a05af66f80da18b308fa7e536912bae

Вот пример функции на PHP, которая возвращает значение подписи запроса по схеме сервер-сервер:

  1. function sign_server_server(array $request_params, $secret_key) {
  2.   ksort($request_params);
  3.   $params = '';
  4.   foreach ($request_params as $key => $value) {
  5.     $params .= "$key=$value";
  6.   }
  7.   return md5($params . $secret_key);
  8. }

Безопасность схемы сервер-сервер основывается на том, что 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 нет нет есть есть

Функции REST API

Справочник по REST API

Другие технологии