Пример API сервера для разработки приложения-клиента

Клиентская часть, клиент, приложение — любое стороннее приложение (в данном случае имеется в виду мобильное приложение), взаимодействующее с данными сервиса посредством REST API методом отсылки запросов в серверную часть и получения от нее результатов.

Ограничения REST API версии 1.0

Для ускорения процесса разработки серверной части будем использовать:

● Протокол HTTP. В следующей версии планируется использование HTTPS (нужна покупка сертификата)

● Передачу названия метода в качестве параметра, а не части пути. В следующей версии планируется использование обоих вариантов.

● Тип запроса — GET. В следующей версии — GET и POST.

● Вывод результата в формате JSON.

● Аутентификация пользователей по логину и паролю. В следующей версии — oAuth 2.0.

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

REST API определяет набор методов, к которым внешнее приложение может совершать запросы и получать ответы.

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

Адрес сервера и формат запроса:

http://server.com/api/{Версия API}/method={Название метода}&{Параметры метода}&{Обязательные параметры запроса}

где:

● Версия API — v1.

● Название метода — из приведенного ниже списка методов.

● Параметры метода — параметры соответствующего метода API.

● Обязательные параметры запроса — будут рассмотрены ниже.

В ответ на запрос приложение получает его результат в формате JSON. Кодировка результата — UTF-8.

Если запрос выполнен успешно, то содержимое его результата выводится в ключе result. Если запрос завершился с ошибкой, то код и текст ошибки выводятся в ключе error.

Общие для всех методов коды и тексты ошибок

Код	Текст	Описание
0	Неизвестная ошибка	Ни один из перечисленных ниже случаев
1	Ошибка авторизации приложения	Неправильная подпись application_signature
2	Ошибка авторизации пользователя	Неизвестный токен access_token
3	Не указан один или несколько обязательных параметров

Настройки приложения

В серверной части необходимо хранить следующую информацию о приложении (таблица в упрощенном виде: application_name|application_key|secret_key):

application_name

string

Название приложения. Предлагается использовать значение:

Service Mobile App

application_key

string

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

service-mobile-app

secret_key

string

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

На момент запуска мобильного приложения таблица приложений будет содержать одну запись — о приложении Service Mobile App. В дальнейшем возможно подключение к REST API других видов клиентских приложений (включая сторонние вебсайты).

Обязательные параметры запроса

application_key

string

Публичный ключ приложения. Рассмотрен выше. Используется для получения на сервере информации о приложении (в частности, его секретного ключа).

application_signature

string

Подпись запроса. Вычисляется для каждого запроса на сервере и в приложении (по одинаковому алгоритму. Необходима для повышения безопасности использования API. Подпись вычисляется по формуле:

application_signature = sha1(parameters + secret_key)

где

● parameters — это конкатенация пар «имя=значение», отсортированных в алфавитом порядке по «имя», где «имя» — это название параметра, передаваемого в метод API, «значение» — значение параметра. Разделитель в конкатенации не используется. При расчете учитываются все параметры запроса (включая название метода), кроме самого application_signature. Строка не должна быть в формате URL-encode, кодировка должна быть UTF-8.

● secret_key — секретный ключ приложения.

access_token

string

Идентификатор сессии залогиненного пользователя. Для метода login он передается пустой, для всех других методов передается значение, полученное в результате успешного выполнения метода login. При успешном логине значение access_token сохраняется в отдельной таблице (в упрошенном виде: user_id|access_token) на сервере. Полученное в каждом дальнейшем запросе от приложения значение сравнивается с хранимым на сервере. Их идентичность означает, что пользователь залогинен в приложении. Именно access_token используется на сервере для получения идентификатора пользователя, в контексте которого выполняются все последующие после метода login (и до метода logout, если он будет вызван) методы.

В данный список не вошел параметр method. Подразумевается, что его обязательность очевидна.

Метод login

Предпринимает попытку аутентификации пользователя.

Параметры

Название

Тип

Требуется

Описание

username

string

Да

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

password

string

Да

Хэш от информации пользователя, вычисляемый по функции:

sha1(user_login + sha1( user_password ) )

где

● user_login и user_password — введенные в форму логина значения

Результат

Название	Тип	Описание
access_token	string	Идентификатор сессии пользователя

Коды и тексты ошибок

Код	Текст
100	Неправильный пароль или пользователь неактивен

Пример вызова

http://server.com/api/v1/method=login&username=email@yandex.ru&password=h7NWWD9N&
application_key=service-mobile-app&application_signature=md3f45ydeS0&access_token=

Пример результата

{

“result”: {

“access_token”: “wbJherh4339c”

}

Пример ошибки

{

“error”: {

“error_code”: 100,

“error_text”: “Неправильный пароль или пользователь неактивен”

Что должно происходить на сервере в случае получения правильно введенных в приложении логина и пароля

1. Из таблицы пользователей выбирается пользователь, с указанным username.

2. Считается password по указанной в описании параметров метода формуле.

3. Если эти значения совпадают с полученными от приложения, то в таблице сессий создается новая запись user_id|access_token (где access_token — сгенерированный на сервере по формуле sha1( user_id + timestamp + sha1(user_password) ) идентификатор).

4. access_token отдается приложению в качестве результата.

Метод logout

Разлогинивает текущего пользователя.

Параметры

Нет

Результат

Нет

Что должно происходить на сервере

Из таблицы сессий пользователя удаляется запись с access_token (или выставляется флаг ее неактивности, если нужно сохранять лог всех сессий).

Метод users.getInfo

Возвращает информацию о пользователях. В версии 1.0 — только о текущем пользователе.

Параметры

Нет

Результат

После успешного выполнения возвращает массив объектов пользователей. В версии 1.0 этот массив будет состоять из одного элемента со следующими полями:

Название	Тип	Описание
login	string	Логин
email	string	Электронная почта
first_name	string	Имя
last_name	string	Фамилия
city	string	Город
school	string	Школа
class	string	Класс

Коды и тексты ошибок

Нет

Пример результата

{

“result”: [

{

“login”: “testlogin”,

“email”: “email@yandex.ru”,

“first_name”: “Иван”,

“last_name”: “Пупкинсон”,

“city”: “Москва”,

“school”: “Среднеобразовательная школа №3333333”,