Avril REST API

Version 1.0.10

Протокол представляет собой набор HTTP/REST команд клиент-серверного взаимодействия. Данные содержатся в JSON формате в теле HTTP.

Внимание! Адресная строка, а также тело JSON являются case sensitive; При запросе HTTP-PUT, если в теле JSON запроса отсутствуют какие-либо необязательные параметры (null-значения допустимы), соответствующие данным параметрам поля объекта в БД станут null;

Серверная часть реализует полный набор CRUD операций над объектами, представляющими собой записи в БД. Типы операций:

• CREATE (HTTP-POST) – создание нового объекта;
• READ (HTTP-GET) – получение информации об объекте;
• UPDATE (HTTP-PUT) – обновление существующего в БД объекта, либо его создание в случае отсутствия;
• DELETE (HTTP-DELETE) – удаление существующего в БД объекта.

Серверный REST-сервис называется AvrilDock.

Адрес сервиса: http://%host%:%port%/AvrilDock/rest/%service%

, где: %host% – хост, на котором развернуто серверное приложение; %port% – порт, на котором развернуто серверное приложение; %service% -имя сервиса (группы команд).

Example:
http://188.138.122.184:8080/AvrilDock/rest/jobservice

При отсутствии исключительных ситуаций в JSON теле ответного сообщения значение по ключу errCode = 0. При возникновении исключения при обработке запроса в JSON теле значение по ключу errCode < 0 (подробнее в разделе списка кодов ошибок), а также имеется описание ошибки по ключу errMsg.

• Работа с организациями (organizationservice)
• Работа с нарядами (jobservice)
• Работа с пользователями (userservice)
• Работа со справочником статусов нарядов (stateservice)
• Работа со справочником срочностей нарядов (urgencyservice)

Каждый сервис имеет функционал проверки статуса с помощью HTTP-GET запроса по адресу:
http://%host%:%port%/AvrilDock/rest/%servicename%/status

В теле ответа функционирующий сервис возвращает JSON следующего вида:
{“status”:“%ServiceName% is running…”,“errCode”:0}

Before working with Avril API it is necessary to fetch a session token through the login procedure. It can be made with HTTP-POST request to the following URL:

http://%host%:%port%/auth/realms/avril-realm/protocol/openid-connect/token

Example: http://188.138.122.184:8180/auth/realms/avril-realm/protocol/openid-connect/token

The body should contain the following information:

client_id=avril-web&username=%username%&password=%password%&grant_type=password

where:
%username% - user name of the user, which should be logged in
%password% - the password of this user

If the login information is right, the server replies with status “200 OK” and the response body like this:

{
  "access_token":"%accesstoken%",
  "expires_in":%expiresinmillis%,
  "refresh_token":"%refreshtoken%",
  "token_type":"bearer",
  "id_token":"%idtoken%", 
  "not-before-policy":%not_before_policy%,
  "session-state":"%sessionstate%"
}

where:
%accesstoken% - access token, which should be used to make every subsequent API call
%expiresinmillis% - the token will expire after this number of millis elapse
%refreshtoken% - refresh token
%idtoken% - token id
%sessionstate% - session state

The most important field is here the %accesstoken%. As mentioned above, this token should be used with every subsequent API call.

Caution: the port which is used in this request, is normally not the same, which is used in all other requests! Because the authentication service runs on other Wildfly instance. This means for our first phase that here the port 8180 should be used, but in all other requests 8080.

Команды данной группы относятся к адресу:

http://%host%:%port%/AvrilDock/rest/organizationservice

• create, update, delete - superadmin
• read – all users of particular organization

Элементами объекта являются:

• id (unique identifier of an organization, primary key in the DB) - mandatory
• addMS (серверная дата и время в миллисекундах создания)
• updMS (серверная дата и время в миллисекундах последнего обновления)
• name (имя) - обязательный
• country (страна) - необязательный
• city (город) – необязательный
• address (адрес) – необязательный
• postCode (почтовый индекс) – необязательный

HTTP-POST по адресу: /organizationservice

В теле JSON с элементами: id (обязательный), name (обязательный), country, city, address, postCode.

http-state = CREATED

HTTP-PUT по адресу: /organizationservice

В теле JSON с элементами: id (обязательный), name (обязательный), country, city, address, postCode.

В случае отсутствия объекта в БД новый объект будет создан.

В случае обновления http-статус = OK.

В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND В случае создания результат аналогичен п.1.

HTTP-DELETE по адресу: /organizationservice/%id% , где %id% - идентификатор организации для удаления. При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.

При успешном выполнении http-статус = OK. В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.

HTTP-GET по адресу: /organizationservice

Выполняет поиск всех не удаленных (delMS=0) объектов организаций.

HTTP-GET по адресу: /organizationservice?updMS=%updMS%

Выполняет поиск всех не удаленных (delMS=0) объектов организаций, которые были обновлены после %updMS%.

http-статус ответного сообщения = OK, в теле массив организаций organizations в JSON (может быть пустой, если ничего не найдено).

HTTP-GET по адресу: /organizationservice/%id%

Выполняет поиск организации с идентификатором %id%, которая не была удалена.

HTTP-GET по адресу: /organizationservice/%id%?updMS=%updMS%

Выполняет поиск организации с идентификатором %id%, которая была обновлена после %updMS% и не была удалена.

http-статус ответного сообщения = OK, в теле организация organization в JSON. В случае отсутствия организации по заданным условиям http-статус ответного сообщения = NOT_FOUND.

Команды данной группы относятся к адресу: http://%host%:%port%/AvrilDock/rest/jobservice

• create, update, delete – superadmin, admin
• read – any registered user

The important task object elements are:

• id -
• addMS - task creation timestamp in millis
• updMS - update timestamp in millis,
• userId - id of user, which is assigned to this task
• orgId - organization id of current organization
• urgencyId - usually: 1 - high, 2 - normal, 3 - low
• stateId - task status
• resolvedMS - resolved timestamp in millis
• delMS - deleted timestamp in millis
• title - task title
• description - task description
• field1 - field5 - custom fields (“flexible” fields)
• address - address text
• latitude - latitude
• longitude - longitude
• questionnaireId - id of associated questionnaire, which should be answered by the assigned user when task will be set to “resolved”
• questionnaireQuestions - questionnaire questions
• questionnaireAnswers - questionnaire answers
• resolved - boolean flag indicating if this task is resolved or not

HTTP-POST по адресу: /jobservice

В теле JSON с элементами:

• userId (обязательный),
• orgId (обязательный),
• urgencyId (обязательный),
• stateId (обязательный),
• title
• description
• address
• latitude
• longitude
• description
• field1
• field2
• field3
• field4
• field5

Регистрирует новый наряд в БД с привязкой к пользователю и проекту.

http-статус = CREATED. В теле id созданного наряда в JSON.

HTTP-PUT по адресу: /jobservice

В теле JSON с элементами:

• id,
• userId (mandatory),
• projectId (mandatory),
• urgencyId (mandatory),
• stateId (mandatory),
• title (mandatory),
• description,
• field1 – field5.

Если id не задан или наряда с таким id не существует, то новый наряд будет создан.

В случае обновления http-статус = OK.
В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND
В случае создания результат аналогичен п.1.

HTTP-DELETE по адресу:

/jobservice/%id%

,где %id% - id наряда для удаления.

При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.

При успешном выполнении http-статус = OK.
В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.

HTTP-GET по адресу:

/jobservice

Выполняет поиск всех не удаленных (delMS=0) объектов нарядов

HTTP-GET по адресу:

/jobservice?updMS=%updMS%

Выполняет поиск всех не удаленных (delMS=0) объектов нарядов, которые были обновлены после %updMS%.

http-статус ответного сообщения = OK, в теле массив нарядов jobs в JSON (может быть пустой, если ничего не найдено).
Простой пользователь получит массив нарядов, назначенных только на данного пользователя.

HTTP-GET по адресу: /jobservice/%id%

Выполняет поиск наряда с идентификатором %id%, который не был удален.

HTTP-GET по адресу: /jobservice/%id%?updMS=%updMS%

Выполняет поиск наряда с идентификатором %id%, который был обновлен после %updMS% и не был удален.

http-статус ответного сообщения = OK, в теле проект project в JSON. В случае отсутствия наряда по заданным условиям http-статус ответного сообщения = NOT_FOUND.

„Ordinary“ user (NOT admin) will receive the task only if this task is assigned to him.

Команды данной группы относятся к адресу:

http://%host%:%port%/AvrilDock/rest/userservice

• create – superadmin
• update, delete – superadmin, admin
• read – все (простые пользователи имеют доступ только к собственному объекту)

Элементами объекта являются:

• id (уникальный глобальный id пользователя) – обязательный
• updMS (серверная дата и время в миллисекундах последнего обновления)
• orgId (идентификатор организации пользователя) – обязательный

HTTP-POST по адресу: /userservice В теле JSON с элементами: id (необязательный), orgId (обязательный) Регистрирует пользователя в БД с привязкой к организации. Если id не задан, происходит выполнение запроса по текущему пользователю.

http-статус = CREATED.

Запрос аналогичен п.1, но id – обязательный. В случае отсутствия объекта в БД новый объект будет создан.

В случае обновления http-статус = OK. В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND В случае создания результат аналогичен п.1.

HTTP-DELETE по адресу: /userservice/%id% , где %id% - идентификатор пользователя для удаления. При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.

При успешном выполнении http-статус = OK. В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.

HTTP-GET по адресу: /userservice Выполняет поиск всех не удаленных (delMS=0) объектов.

http-статус ответного сообщения = OK, в теле массив пользователей users в JSON (может быть пустой, если ничего не найдено).

Если в элементе массива users отсутствует orgId, то это означает, что пользователь зарегистрирован, но еще не был привязан к организации.

HTTP-GET по адресу:

http://%host%:%port%/AvrilDock/rest/userservice/%id%

Выполняет поиск не удаленного (delMS=0) объекта по заданному id.

http-статус ответного сообщения = OK, в теле объект пользователя user в JSON. Если у пользователя user отсутствует orgId, то это означает, что пользователь зарегистрирован, но еще не был привязан к организации. В случае отсутствия пользователя по заданным условиям http-статус ответного сообщения = NOT_FOUND.

Команды данной группы относятся к адресу:

http://%host%:%port%/AvrilDock/rest/stateservice

read - все

Элементами объекта являются:

id (уникальный глобальный id статуса)
name (имя статуса)

HTTP-GET по адресу: /stateservice

http-статус ответного сообщения = OK, в теле массив статусов states в JSON (может быть пустой, если ничего не найдено).

Команды данной группы относятся к адресу: http://%host%:%port%/AvrilDock/rest/urgencyservice

read - все

Элементами объекта являются: id (уникальный глобальный id срочности)
name (имя срочности)

HTTP-GET по адресу: /urgencyservice

http-статус ответного сообщения = OK, в теле массив срочностей urgencies в JSON (может быть пустой, если ничего не найдено).

При успешной обработке запроса в теле JSON ответного сообщения ключу errCode = 0 При возникновении исключения или конфликтной ситуации при обработке запроса в JSON значение ошибки по ключу errCode < 0 и имеется errMsg. HTTP-статус ответного сообщения соответствует типу возникшей ошибки.

Возможные HTTP-статусы ответного сообщения: OK – запрос успешно выполнен CREATED – объект успешно создан BAD_REQUEST – некорректный запрос NOT_MODIFIED – ошибка создания/изменения объекта NOT_FOUND – объект удален (помечен на удаление) или не найден CONFLICT – при выполнении запроса возникла конфликтная ситуация (как правило, нарушение уникальности записи или попытка записи с несуществующим дочерним объектом по внешнему ключу) INTERNAL_SERVER_ERROR – ошибка при работе с БД/datasource, либо неотловленное исключение

Возможные коды ошибок в JSON теле ответного сообщения:

int ERR_UNKNOWN = -1;
 
// Database errors
int ERR_DATASOURCE_INVALID = -2;
int ERR_SQLQUERY_EXECUTION_FAILED = -3;
int ERR_SQLQUERY_PREPARING_PARAMS_FAILED = -4;
int ERR_DUBLICATE_UNIQUE_NAME = -5;
 
// Common system errors
ERR_NO_SUCH_USER = -6;
ERR_INCORRECT_INPUT_PARAMETERS = -7;
 
// OrganizationService errors
ERR_CREATE_ORG_DB = -8;
ERR_UPDATE_ORG_DB = -9;
ERR_DELETE_ORG_DB = -10;
ERR_SELECT_ORG_DB = -11;
 
// UserService errors
ERR_CREATE_USER_DB = -12;
ERR_UPDATE_USER_DB = -13;
ERR_DELETE_USER_DB = -14;
ERR_SELECT_USER_DB = -15;
ERR_SELECT_USER_KEYCLOAK = -16;
 
// ProjectService errors
ERR_CREATE_PROJ_DB = -17;
ERR_UPDATE_PROJ_DB = -18;
ERR_DELETE_PROJ_DB = -19;
ERR_SELECT_PROJ_DB = -20;
 
// JobService errors
ERR_CREATE_JOB_DB = -21;
ERR_UPDATE_JOB_DB = -22;
ERR_DELETE_JOB_DB = -23;
ERR_SELECT_JOB_DB = -24;

To test API it is possible to use several REST Clients. I've used RESTClient by WizTools.org. The distribution and test requests can be found under: /mnt/sda4/development/_projects/avril/testcases/20170118