vwiki

User Tools

Site Tools

Trace:
avril_api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
avril_api [2017/01/19 11:55] – [Logging in] kalaschnikowavril_api [2018/04/23 15:57] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Avril REST API ======
 +
 +Version 1.0.10
 +
 +===== Introduction =====
 +
 +Протокол представляет собой набор 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 Services Names ====
 +Серверный REST-сервис называется AvrilDock. 
 +
 +Адрес сервиса: http://%host%:%port%/AvrilDock/rest/%service%
 +
 +, где: 
 +%host% – хост, на котором развернуто серверное приложение;
 +%port% – порт, на котором развернуто серверное приложение;
 +%service% -имя сервиса (группы команд).
 +
 +Example:\\ 
 +http://188.138.122.184:8080/AvrilDock/rest/jobservice
 +
 +==== Exceptions ====
 +При отсутствии исключительных ситуаций в JSON теле ответного сообщения значение по ключу errCode = 0. При возникновении исключения при обработке запроса в JSON теле значение по ключу errCode < 0 (подробнее в разделе списка кодов ошибок), а также имеется описание ошибки по ключу errMsg. 
 +
 +==== Command groups ====
 +  * Работа с организациями (organizationservice)
 +  * Работа с нарядами (jobservice)
 +  * Работа с пользователями (userservice)
 +  * Работа со справочником статусов нарядов (stateservice)
 +  * Работа со справочником срочностей нарядов (urgencyservice)
 +
 +
 +
 +==== Request service status ====
 +
 +Каждый сервис имеет функционал проверки статуса с помощью HTTP-GET запроса по адресу:\\ 
 +http://%host%:%port%/AvrilDock/rest/%servicename%/status
 +
 +В теле ответа функционирующий сервис возвращает JSON следующего вида:\\ 
 +{"status":"%ServiceName% is running...","errCode":0}
 +
 +===== Logging in =====
 +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:
 +
 +<code javascript>
 +{
 +  "access_token":"%accesstoken%",
 +  "expires_in":%expiresinmillis%,
 +  "refresh_token":"%refreshtoken%",
 +  "token_type":"bearer",
 +  "id_token":"%idtoken%", 
 +  "not-before-policy":%not_before_policy%,
 +  "session-state":"%sessionstate%"
 +}
 +</code>
 +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.   
 +
 +===== Working with Organizations (organizationservice) =====
 +
 +Команды данной группы относятся к адресу:
 +
 +http://%host%:%port%/AvrilDock/rest/organizationservice
 +
 +==== Access ====
 +  * create, update, delete - superadmin
 +  * read – all users of particular organization
 +
 +==== Organization Object ====
 +
 +Элементами объекта являются:
 +  * id (unique identifier of an organization, primary key in the DB) - mandatory
 +  * addMS (серверная дата и время в миллисекундах создания)
 +  * updMS (серверная дата и время в миллисекундах последнего обновления)
 +  * name (имя) - обязательный
 +  * country (страна) - необязательный
 +  * city (город) – необязательный
 +  * address (адрес) – необязательный
 +  * postCode (почтовый индекс) – необязательный
 +
 +==== Create new organization ====
 +
 +=== Request ===
 +
 +HTTP-POST по адресу: /organizationservice
 +
 +В теле JSON с элементами: id (обязательный), name (обязательный), country, city, address, postCode.
 +
 +=== Response ===
 +
 +http-state = CREATED
 +
 +
 +==== Update organization ====
 +
 +=== Request ===
 +
 +HTTP-PUT по адресу: /organizationservice
 +
 +В теле JSON с элементами: id (обязательный), name (обязательный), country, city, address, postCode.
 +
 +В случае отсутствия объекта в БД новый объект будет создан. 
 +
 +=== Response ===
 +
 +В случае обновления http-статус = OK. 
 +
 +В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND
 +В случае создания результат аналогичен п.1.
 +
 +==== Delete Organization ====
 +
 +=== Request ===
 +HTTP-DELETE по адресу: /organizationservice/%id%
 +, где %id% - идентификатор организации для удаления.
 +При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.
 +
 +=== Response ===
 +
 +При успешном выполнении http-статус = OK. 
 +В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.
 +
 +==== Get all organizations ====
 +
 +=== Request ===
 +
 +HTTP-GET по адресу: /organizationservice
 +
 +Выполняет поиск всех не удаленных (delMS=0) объектов организаций.
 +
 +
 +HTTP-GET по адресу: /organizationservice?updMS=%updMS%
 +
 +Выполняет поиск всех не удаленных (delMS=0) объектов организаций, которые были обновлены после %updMS%. 
 +
 +=== Response ===
 +
 +http-статус ответного сообщения = OK, в теле массив организаций organizations в JSON (может быть пустой, если ничего не найдено).
 +
 +==== Get Organization ====
 +
 +=== Request ===
 +HTTP-GET по адресу: /organizationservice/%id%
 +
 +Выполняет поиск организации с идентификатором %id%, которая не была удалена.
 +
 +
 +HTTP-GET по адресу: /organizationservice/%id%?updMS=%updMS%
 +
 +Выполняет поиск организации с идентификатором %id%, которая была обновлена после %updMS% и не была удалена.
 +
 +=== Response ===
 +
 +http-статус ответного сообщения = OK, в теле организация organization в JSON. 
 +В случае отсутствия организации по заданным условиям http-статус ответного сообщения = NOT_FOUND.
 +
 +
 +===== Working with tasks (jobservice) =====
 +
 +Команды данной группы относятся к адресу:  
 +http://%host%:%port%/AvrilDock/rest/jobservice
 +
 +==== Access ====
 +
 +  * create, update, delete – superadmin, admin
 +  * read – any registered user
 +
 +==== Task object ====
 +
 +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 
 +
 +
 +==== Create New Task ====
 +=== Request ===
 +HTTP-POST по адресу: /jobservice
 +
 +В теле JSON с элементами: 
 +  * userId (обязательный), 
 +  * orgId (обязательный), 
 +  * urgencyId (обязательный), 
 +  * stateId (обязательный), 
 +  * title
 +  * description
 +  * address
 +  * latitude
 +  * longitude
 +  * description 
 +  * field1
 +  * field2
 +  * field3
 +  * field4
 +  * field5
 +
 +
 +Регистрирует новый наряд в БД с привязкой к пользователю и проекту.
 +
 +=== Response ===
 +
 +http-статус = CREATED. В теле id созданного наряда в JSON.
 +
 +==== Update task ====
 +
 +=== Request ===
 +HTTP-PUT по адресу: /jobservice
 +
 +В теле JSON с элементами: 
 +  * id, 
 +  * userId (mandatory), 
 +  * projectId (mandatory), 
 +  * urgencyId (mandatory), 
 +  * stateId (mandatory), 
 +  * title (mandatory), 
 +  * description, 
 +  * field1 – field5.
 +
 +Если id не задан или наряда с таким id не существует, то новый наряд будет создан.
 +
 +=== Response ===
 +В случае обновления http-статус = OK.\\ 
 +В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND\\ 
 +В случае создания результат аналогичен п.1.\\ 
 +
 +==== Delete task ====
 +
 +=== Request ===
 +HTTP-DELETE по адресу: 
 +
 +/jobservice/%id%
 +
 +,где %id% - id наряда для удаления.
 +
 +При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.
 +
 +=== Response ===
 +При успешном выполнении http-статус = OK.\\ 
 +В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.\\ 
 +
 +==== Get all tasks ====
 +
 +=== Request (all) ===
 +HTTP-GET по адресу: 
 +
 +/jobservice
 +
 +Выполняет поиск всех не удаленных (delMS=0) объектов нарядов
 +
 +=== Request (all changed after specific timestamp) ===
 +
 +HTTP-GET по адресу: 
 +
 +/jobservice?updMS=%updMS%
 +
 +Выполняет поиск всех не удаленных (delMS=0) объектов нарядов, которые были обновлены после %updMS%. 
 +
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле массив нарядов jobs в JSON (может быть пустой, если ничего не найдено).\\ 
 +Простой пользователь получит массив нарядов, назначенных только на данного пользователя.\\ 
 +
 +==== Get task by id ====
 +=== Request ===
 +
 +HTTP-GET по адресу: /jobservice/%id%
 +
 +Выполняет поиск наряда с идентификатором %id%, который не был удален. 
 +
 +
 +HTTP-GET по адресу: /jobservice/%id%?updMS=%updMS%
 +
 +Выполняет поиск наряда с идентификатором %id%,  который был обновлен после %updMS% и не был удален.
 +
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле проект project в JSON. 
 +В случае отсутствия наряда по заданным условиям http-статус ответного сообщения = NOT_FOUND.
 +
 +„Ordinary“ user (NOT admin) will receive the task only if this task is assigned to him.
 +
 +
 +===== Working with Users (userservice) =====
 +
 +Команды данной группы относятся к адресу: 
 + 
 +http://%host%:%port%/AvrilDock/rest/userservice
 +==== Доступ ====
 +  * create – superadmin
 +  * update, delete – superadmin, admin
 +  * read – все (простые пользователи имеют доступ только к собственному объекту)
 +
 +==== Объект «Пользователь» ====
 +
 +Элементами объекта являются:
 +  * id (уникальный глобальный id пользователя) – обязательный
 +  * updMS (серверная дата и время в миллисекундах последнего обновления)
 +  * orgId (идентификатор организации пользователя) – обязательный
 +
 +==== Создание нового пользователя ====
 +
 +=== Request ===
 +HTTP-POST по адресу: /userservice
 +В теле JSON с элементами: id (необязательный), orgId (обязательный)
 +Регистрирует пользователя в БД с привязкой к организации.
 +Если id не задан, происходит выполнение запроса по текущему пользователю.
 +=== Response ===
 +
 +http-статус = CREATED.
 +
 +==== Обновление пользователя ====
 +
 +=== Request ===
 +Запрос аналогичен п.1, но id – обязательный.
 +В случае отсутствия объекта в БД новый объект будет создан. 
 +=== Response ===
 +
 +В случае обновления http-статус = OK. 
 +В случае попытки обновления помеченного на удаление объекта http-статус ответного сообщения = NOT_FOUND
 +В случае создания результат аналогичен п.1.
 +
 +==== Удаление пользователя ====
 +
 +=== Request ===
 +
 +HTTP-DELETE по адресу: /userservice/%id%
 +, где %id% - идентификатор пользователя для удаления.
 +При запросе удаления объекта происходит обновление поля delMS объекта на текущую дату и время сервера.
 +=== Response ===
 +
 +При успешном выполнении http-статус = OK. 
 +В случае отсутствия объекта в БД, либо если объект уже был помечен на удаление http-статус = NOT_FOUND.
 +
 +==== Получение всех пользователей ====
 +
 +=== Request ===
 +
 +HTTP-GET по адресу: /userservice
 +Выполняет поиск всех не удаленных (delMS=0) объектов.
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле массив пользователей users в JSON (может быть пустой, если ничего не найдено).
 +
 +Если в элементе массива users отсутствует orgId, то это означает, что пользователь зарегистрирован, но еще не был привязан к организации.
 +
 +==== Получение пользователя ====
 +
 +=== Request ===
 +
 +HTTP-GET по адресу: 
 +
 +http://%host%:%port%/AvrilDock/rest/userservice/%id%
 +
 +Выполняет поиск не удаленного (delMS=0) объекта по заданному id.
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле объект пользователя user в JSON.
 +Если у пользователя user отсутствует orgId, то это означает, что пользователь зарегистрирован, но еще не был привязан к организации.
 +В случае отсутствия пользователя по заданным условиям http-статус ответного сообщения = NOT_FOUND.
 +
 +===== Working with Statuses (stateservice) =====
 +
 +Команды данной группы относятся к адресу:
 +
 +http://%host%:%port%/AvrilDock/rest/stateservice
 +
 +==== Access ====
 +read - все
 +
 +==== Status Object ====
 +
 +Элементами объекта являются:
 +
 +id (уникальный глобальный id статуса)\\ 
 +name (имя статуса)\\ 
 +
 +==== Get all work order statuses ====
 +
 +=== Request ===
 +HTTP-GET по адресу: /stateservice
 +
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле массив статусов states в JSON (может быть пустой, если ничего не найдено).
 +
 +===== Working with Urgencies (urgencyservice) =====
 +
 +Команды данной группы относятся к адресу:
 +http://%host%:%port%/AvrilDock/rest/urgencyservice
 +
 +==== Access ====
 +read - все
 +
 +==== Объект «Срочность» ====
 +
 +Элементами объекта являются:
 +id (уникальный глобальный id срочности)\\ 
 +name (имя срочности)\\ 
 +
 +==== Get All Urgencies ====
 +
 +=== Request ===
 +HTTP-GET по адресу: /urgencyservice
 +
 +=== Response ===
 +http-статус ответного сообщения = OK, в теле массив срочностей urgencies в JSON (может быть пустой, если ничего не найдено).
 +
 +===== Error codes =====
 +При успешной обработке запроса в теле JSON ответного сообщения  ключу errCode = 0
 +При возникновении исключения или конфликтной ситуации при обработке запроса в JSON значение ошибки по ключу errCode < 0 и имеется errMsg. HTTP-статус ответного сообщения соответствует типу возникшей ошибки.
 +
 +Возможные HTTP-статусы ответного сообщения:
 +OK – запрос успешно выполнен
 +CREATED – объект успешно создан
 +BAD_REQUEST – некорректный запрос
 +NOT_MODIFIED – ошибка создания/изменения объекта
 +NOT_FOUND – объект удален (помечен на удаление) или не найден
 +CONFLICT – при выполнении запроса возникла конфликтная ситуация (как правило, нарушение уникальности записи или попытка записи с несуществующим дочерним объектом по внешнему ключу)
 +INTERNAL_SERVER_ERROR – ошибка при работе с БД/datasource, либо неотловленное исключение
 +
 +Возможные коды ошибок в JSON теле ответного сообщения:
 +<code java>
 +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;
 +</code>
 +
 +
 +
 +
 +===== How to test API =====
 +To test API it is possible to use several REST Clients. I've used [[https://github.com/wiztools/rest-clien|RESTClient]] by WizTools.org. The distribution and test requests can be found under: /mnt/sda4/development/_projects/avril/testcases/20170118