Какие REST-команды должно поддерживать наше предложение?

Версия Кожухова С.А.

Если Вам есть, что вставить, пишите вставку полужирным шрифтом Если Вы хотите что-либо убрать, отметьте это курсивом

ВНИМАНИЮ РАЗРАБОТЧИКОВ ИЗ СОСЕДНИХ ВЕТОК! Данный документ не является окончательным, и будет ещё весьма и весьма долгое время переосмысливаться всеми участниками данной ветки.

Общие сведения об HTTP-запросах и HTTP-ответах

Наша программа способна принимать и обрабатывать только POST-запросы. При этом, все POST-запросы направляются строго по адресу:

http://localhost:8080/Rest

Разумеется, что когда весь наш проект будет перемещён на удалённый сервер, то первая часть адреса (до двоеточия) слегка поменяется.

Ответы возвращаются исключительно в JSON-формате.

Общий формат запросов

Любой запрос обязательно содержит поле action. Он означает конкретное действие, которое Вы хотите предпринять. Точнее - что Вы конкретно хотите от приложения. Формат всех остальных полей зависит от того, что конкретно Вы задали в поле action

Данное поле должно содержать целочисленное значение. Это значение соответствует определённому действию, предпринимаемому программой. Список всех действий вместе с соответствующими им константами, находится в файле humaninweb/src/java/rest/RestActions.java. Создатели клиентского приложения на Android'е могут без особой опаски включать этот файлик в свой собственный проект использовать одну из этих констант. Всем остальным требуется "перевести" этот файл с языка Java на свой родной язык программирования.

Общий формат ответов

Все ответы представляют собой JSON-ответ, содержащий в своём составе всего три поля.

• errno - код ошибки, либо 0 в случае, если запрос был завершён без ошибки
• error - текст ошибки, либо "ok" в случае, если запрос был завершён без ошибки
• data - собственно сами результаты запроса в виде JSON-объекта. Обратите внимание, что если запрос был завершён с ошибкой, то эти поля могут и отсутствовать.

Список всех распространённых ошибок находится в файле humaninweb/src/java/rest/RestErrors.java. Создатели приложения на Android'е могут свободно включить этот файл в свой проект, однако остальным пользователям потребуется "перевести" его с языка Java на тот язык программирования, на котором они работают.

Список ошибок, которые могут быть при выполнении запросов

Все ошибки подразделяются на четыре категории.

1. Ошибки пользователя RestErrors.OK - успешное выполнение запроса, нет ошибки

RestErrors.UNSUPPORTED - возникает в том случае, если Вы неправильно указали номер команды. Для того, чтобы её избежать, пользуйтесь для задания поля action только набором предопределённых констант, прописанных в файле RestActions.java. В этом случае данная ошибка будет целиком находиться в нашей зоне ответственности.

RestErrors.TYPE_MISMATCH_ERROR - возникает в том случае, если Вы либо не передали на сервер нужное поле, либо передали его, однако данные были представлены в ошибочном формате. Данная ошибка может находиться как в нашей, так и в Вашей зоне ответственности.

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

RestErrors.FREE_VERSION_ERROR - возникает в том случае, если пользователь попытался использовать бесплатную версию продукта для совершения операции, которая доступна только в его платной версии.

RestErrors.POLITICIAN_NOT_FOUND, RestErrors.USER_NOT_FOUND, RestErrors.SITE_NOT_FOUND - попытка обратиться к сущностям, которые отсутствуют в базе данных, либо были из неё уже удалены, либо ошибка в указании ID сущности.

2. Ошибки работы с базой данных.

Данное приложение не может генерировать ошибки с номерами 1000 и выше. Все эти ошибки "по-умолчанию" генерируются СУБД. Они могут возникать в том случае, если при выполнении SQL-запроса СУБД вернула ошибку, однако наш сервлет не смог корректно его обработать, после чего просто "пропустил" его до клиента. В этом случае данные ошибки являются явным свидетельством косяка с нашей стороны.

3. Ошибки HTTP-соединения.

Они имеют номера 400 и 500 и подробно описаны в Википедии. Их характерной особенностью является то, что они пишутся не в теле ответа, как ранее, а в его заголовке. Их появление означает, что наш сервлет даже и не приступил к выполнению Вашего запроса.

4. Ошибка подключения к сети.

Классификация запросов

Все запросы делятся на три категории.

1. Запросы, которые может выполнить любой посетитель. Они имеют номера от 0 до 100.
2. Запросы, которые могут выполнить только авторизованные пользователи. Они имеют номера от 101 до 200. Попытка выполнения этих запросов со стороны неавторизованных приложений всегда приводит к ошибке RestErrors.AUTH_ERROR.
3. Запросы, которые могут выполнить только администраторы. Они имеют номера от 201 и выше. Попытка их выполнения со стороны неавторизованного клиентского приложения, либо со стороны клиентского приложения, авторизованного обычным пользователем, приводят к ошибке RestErrors.AUTH_ERROR

Авторизационный токен и запрос RestActions.AUTH

В прошлом разделе было введено понятие "авторизованного приложения".

Клиентское приложение является авторизованным, если оно получило от нашего сервлета специальный авторизационный ключ - некоторую строку длиной до 128 символов. Этот авторизационный ключ Ваше приложение должно посылать на сервер всякий раз, как только оно запрашивает у него совершение действий с номерами от 101 и выше.

1. Как получить авторизационный ключ?

Для этого надо обратиться к нашему приложению со специальным POST-запросом, содержащим всего три поля.

action: значение целочисленной константы RestActions.AUTH login: Логин пользователя, с которого надо авторизоваться. password: Пароль пользователя, с которого надо также авторизоваться. Пароль передаётся в незашифрованном виде.

Формат ответа на данный запрос выглядит следующим образом, в случае его успешности:

{ "errno": 0, "error": "ok", "data": { "token": "lkkjnbjHUHbniyGkkKHkjjKKUHBK8437KHUHUk" } }

где вон та абра-кадабра - это и есть Ваш авторизационный ключ

Обратите внимание также и на то, что если неправильно задать Логин и Пароль, то будет сгенерирована ошибка типа RestErrors.AUTH_ERROR.

2. Как применить авторизационный ключ.

Если Вы выполняете запросы с номерами от 101 и выше, то наряду с полем action, содержащим номер конкретного действия, Вы также должны передавать и поле token, в котором будет указан Ваш авторизационный ключ.

3. Срок действия авторизационного ключа.

В случае, если зарегистрирован обычный пользователь, то авторизационный ключ действует в течение 24 часов после его выдачи, а при каждом новом 100-м и 200-м запросе он автоматически продлевается ещё на 24 часа.

Для администраторов авторизационный ключ активен в течение трёх часов после его получения. В тоже время, срок его действия продлевается каждым новым 100-м и 200-м запросом.

Для root'а всё тоже самое, однако срок действия авторизационного ключа составляет 30 мин.

Условные обозначения, используемые далее в этой статье.

Описанная в пункте 1 предыдущего раздела команда может быть лаконично записана на некотором символьном метаязыке как:

AUTH(login,password)

Такое условное обозначение подразумевает следующее: если Вы пришлёте POST-запрос, имеющий поля action, установленное в RestCommands.AUTH, а также поля login и password, то тем самым Вы выполните авторизацию.

Аналогично и обозначение TECH_SUPPORT(message,email) означает, что речь идёт о POST-запросе с полями action, message, email, в котором action имеет значение RestActions.TECH_SUPPORT.

Однако, если речь идёт о запросе GET_POLITICIAN_INFO(id), то для него потребуются не два поля, а целых три, а именно: action, установленная в RestCommands.GET_POLITICIAN_INFO, token и id. Почему? Потому что, как это уже было сказано выше, все запросы с номерами от 100 и выше, в теле которых отсутствуют сведения об авторизационном ключе (поле token), гарантированно приводят к ошибке.

Список все REST-запросов

Запрос на авторизацию (запрос номер 0)

AUTH(login,password)

О нём было сказано выше.

Запросы, не требующие авторизации (апросы номер 1-100)

TECH_SUPPORT(title,body,email)

Отослать письмо в тех-поддержку. title - его заголовок, body - тело письма, email - адрес отправителя письма

FEEDBACK(title,body,email)

Отослать письмо по форме обратной связи. Параметры запроса те же, что и в TECH_SUPPORT

ADD_REVIEW_UNAUTHORIZED(name,body)

Добавить запрос, вариант для неавторизованного пользователя. В качестве name указывается имя посетителя, а в качестве body - тело запроса.

LIST_REVIEWS()

Просмотр всех отзывов

PASSWORD_REMINDER_REQUEST(login)

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

PASSWORD_REMINDER(login,reminder_token)

Добавить запрос, вариант для авторизованного пользователя. Задаются логин и временный пароль, выданный системой

Запросы, на которые имеют право только авторизованные пользователи (запросы номер 101-200)

ADD_REVIEW_AUTHORIZED(body)

Добавить запрос, вариант для авторизованного пользователя

GET_POLITICIAN_LIST()

Получить список всех политиков

GET_POLITICIAN_INFO(severe_id)

Получить подробную информацию о конкретном политике с конкретным ID

PASSWORD_REMINDER_REQUEST(body)

Добавить запрос, вариант для авторизованного пользователя

SET_CURRENT_USER_INFO(password)

Изменить пароль

Команды, которые вправе выполнять только администраторы (запросы с номерами 201 и выше)

(и то есть шанс, что они могут схлопотать RestErrors.AuthError

ADD_USER(login,password,admin)

Добавить нового пользователя. admin принимает значение 0, если добавляется обычный пользователь, и любое значение, отличное от нуля, если добавляется администратор

REMOVE_USER(severe_id)

Удалить пользователя

GET_USER_INFO(severe_id)

Получить подробную информацию о пользователе

GET_USER_LIST()

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

SET_USER_INFO(severe_id,login,password,admin)

Изменить информацию о пользователе. Не все перечисленные в скобках поля обязательны.

ADD_POLITICIAN(names)

Добавить политика. В строке names указываются все формы его названий, перечисленные через точку с запятой.

REMOVE_POLITICIAN(severe_politician_id)

Удалить политика

SET_POLITICIAN_INFO(severe_politician_id,names)

Изменить список имён политика

GET_SITES_LIST()

Вернуть список сайтов, добавленных данным администратором

ADD_SITE(url)

Добавить сайт

REMOVE_SITE(severe_site_id)

Удалить сайт

SET_SITE_INFO(severe_site_info,url)

Изменить ииформацию о сайте

GET_SITE_INFO(severe_site_info)

Получить информацию о сайте

Тестирование приложения

Для того, чтобы протестировать работоспособность нашего сервлета, необходимо также написать определённые операторы, однако их надо описать уже не на языке Java, а на языке Javascript. Для этого

1. Открываем Google Chrome.
2. Запускаем http://localhost:8080/Rest-test
3. Кликаем правой кнопкой мышки по консоли, затем нажимаем "Просмотреть код элемента", открываем вкладку Console.
4. Вводим следующую REST-команду к нашему сервлету (например):

submitTestRequest({"action":RestActions.AUTH,"login":"Yuri","password":"Gagarin"});