ОПЫТ ПРОЕКТИРОВАНИЯ API РАСПИСАНИЯ МЕРОПРИЯТИЙ УНИВЕРСИТЕТА Текст научной статьи по специальности «Компьютерные и информационные науки»

Опыт проектирования API расписания мероприятий

Университета

П.С. Гуляев, О.В. Минакова

Воронежский государственный технический университет

Аннотация: в работе представлено описание процесса проектирования API для создания интеграционного сервиса университетского портала, предоставляющего информацию о проводимых в университете мероприятиях. В ходе проведенного сравнительного анализа осуществлен выбор REST API. Разработка API расписания мероприятий выполнена с использованием классической методологии разработки ПО, включая анализ требований, обоснование выбора архитектуры, проектирование моделей данных. Описана и обоснована модель данных, позволяющая удовлетворять возможным запросам на извлечение различной информации об организуемых Университетом мероприятиях. В ходе проектирования обоснован и сформирован набор возможных запросов с третьим уровнем зрелости. Прототип сервиса, поддерживающий разработанное API, документирован и реализован на Фреймворке SpringBoot Рабочий проект доступен на github для обсуждения, оценки и дальнейшей модернизации.

Ключевые слова: разработка программ, прикладной программный интерфейс, проектирование веб-сервисов, модель данных, расписание мероприятий, календарь

протокол HTTP, и REST API являются наиболее распространенным форматом для создания веб-приложений и наиболее распространенная форма подключения микросервисов: когда REST API публично раскрывается как веб-сервис, каждый компонент (или сервис), предоставляемый веб-сервисом, представляется клиенту в виде ресурса. Клиенты могут получить доступ к этим ресурсам через общий интерфейс, который принимает различные команды HTTP, такие как GET, POST, DELETE и PUT. [1].

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

Удаленный вызов процедур (RPC) — это спецификация, позволяющая удаленное выполнение функций; RPC расширяет концепцию локального вызова процедур и заменяет ее контекстом HTTP API. Чаще всего он используется в качестве клиентского API для внутренних микросервисов. Для прямой интеграции между одним провайдером и потребителем он может сократить время, необходимое для передачи больших объемов метаданных. К недостаткам можно отнести высокую уязвимость к сбоям, поскольку в процесс вовлечена система связи,

ВВЕДЕНИЕ

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

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

Целью данной работы является представление проектирования API расписания мероприятий Университета по классической модели, включающий инженерию требований, проектирование модели данных, конструирование прототипа сервера и его оценку.

1. Выбор API

В настоящее время наиболее распространены REST, SOAP, gRPC как архитектура для интеграции и взаимодействия веб-сервисов.

REST описывает организацию клиент-сервер, при которой внутренние данные предоставляются клиенту через формат сообщений JSON или XML. Архитектура REST API обычно опирается на

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

Как вариант архитектуры RPC, gRPC был создан компанией Google для ускорения передачи данных между микросервисами и другими системами, требующими связи. gRPC преодолевает проблемы скорости и веса и использует формат обмена сообщениями Protobuf (протокол буфер) для повышения эффективности обмена сообщениями.

2. Анализ архитектуры информационной СИСТЕМЫ УНИВЕРСИТЕТА

Большинство информационных систем Университета используют многоуровневую архитектуру, соответствующую модели B2b, ориентированной на предоставление образовательных услуг. На верхнем уровне портал предоставляет пользователям единую точку входа для получения различных услуг и их авторизации, а также веб-интерфейс для доступа к справочной информации. Уровень 2: Общие услуги — это услуги, необходимые участникам образовательного процесса, от деканов до обычных посетителей мероприятия, и определяемые основными и вспомогательными бизнес-процессами организации. Прикладной уровень обеспечивает базовую функциональность для учебной организации и может состоять из нескольких отдельных информационных систем.

Система управления учебным контентом (LCMS) позволяет регистрировать, хранить, собирать,

управлять, оформлять и публиковать любую информацию организации.

Система управления обучением (LMS) регистрирует пользователей, отслеживает курсы в каталоге, записывает данные от учеников и обеспечивает возможности поиска и отчетности для пользователей.

Система оценки - это служба, которая измеряет успеваемость и другие достижения учащихся по конкретным целям, используя различные инстру -менты. Поскольку универсальное решение для это системы нет, в нашем ВУЗе - это личный кабинет обучающегося, который позволяет собирать и хранить работы студентов, а также подсистемы деканатов, которая отслеживает общую успеваемость [3].

На нижнем уровне Базы данных, используемые различными компонентами в этой структуре.

Это обуславливает применение REST API как универсального решения при любой интеграции [4]. Как показал проведенный анализ аналогичных решений [5], а также учитывая, что RPC ориентирует разработчиков на работу с операциями, кроме того, это семейство протоколов и стандартов, которое использует HTTP как транспортный протокол, в то время как REST использует все тонкости протокола HTTP: манипулирование информацией, кэширование, аутентификация, сжатие трафика, передача данных в теле сообщений,

Рис. 1. Архитектура существующих ИС Университета

3. Обоснование проектных решений

Основной проблемой, с которой сталкиваются при проектировании API - чрезмерная выборка и недостаточная выборка.

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

Проблема недостаточной выборки возникала, когда клиенту приходится делать несколько запросов, чтобы получить всю информацию, которая ему нужна. Чтобы предотвратить неполную выборку, нужно было созданы составные конечные точки [11].

Для поиска компромисса важно определить все возможные сценарии работы с интегрируемой системой, т.е. использование расписания мероприятий Университета.

При моделировании вариантов использования было выделено три роли будущего пользователя API расписания:

- посетитель мероприятия, то есть все сотрудники, обучающие и гости университета, принимающие пассивное участие в мероприятиях;

- участник или член университетского сообщества, включая сотрудников, обучающихся и преподавателей, непосредственно участвующих в образовательном процессе,

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

Для выявления всех вариантов потребностей обращения к расписанию был проведен опрос студентов Университета. К числу наиболее часто возникающих проблем были отнесены - составление личного расписания, проверка изменений в расписании, поиск свободной аудитории. Моделирование требований с помощью диаграмм прецедентов представлено на рис. 2-4.

Рис. 2. Диаграмма прецедентов сценария использования «верификации» мероприятий

Посетитель может получить информацию о мероприятии по запросу - названия, места и времени.

Студенты используют те же функции, что и посетитель, но им доступна подробная информация о мероприятиях и расписании ВУЗа. Также им необходимо отслеживать изменения, осуществлять поиск по критериям - группа, преподаватель, аудитория, а также создавать и интегрировать мероприятия в личном календаре. Преподаватель

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

Организатору мероприятий требуется создавать, удалять, изменять информацию о мероприятии, то есть вносить изменение в расписание.

Рис. 3. Диаграммы прецедентов для сценария навигация по расписанию

Рис. 4. Диаграммы прецедентов для сценария работы с расписанием

Такое разнообразие сценариев требовало использование всех четырех методов HTTP запросов. Запросы GET могут быть использованы только для получения информации о мероприятиях и никоим образом не предоставят возможности их изменения. Поскольку запросы GET не изменяют состояние ресурса, они считаются безопасными методами.

Кроме того, API GET должны быть идемпо-тентными. Выполнение нескольких идентичных запросов должно приводить к одному и тому же результату каждый раз, пока другой API (POST или PUT) не изменит состояние ресурса на сервере. Если запрос-URI ссылается на процесс, производящий данные, то в качестве объекта в ответе должны быть

возвращены созданные данные, а не исходный текст процесса, если только этот текст не является результатом процесса.

Метод POST может быть использован для создания нового мероприятия. Ответы на этот метод нельзя кэшировать, если ответ не содержит соответствующих полей заголовка Cache-Control или Expires. POST не является ни безопасным, ни идемпотентным, и вызов двух идентичных запросов POST приведет к двум разным ресурсам, содержащим одну и ту же информацию (кроме идентификаторов ресурсов), поэтому на сервисе должны быть предусмотрены разграничение запросов на к каждому свой

Метод PUT был использован в первую очередь для обновления существующего ресурса (если ресурс не существует, API может решить, создавать новый ресурс или нет).

Для организатора мероприятия требуется DELETE для удаления созданного мероприятия, если повторный DELETE запрос к ресурсу часто сопровождается 404 (NOT FOUND) кодом HTTP по причине того, что ресурс уже удален (например, из базы данных) и более не доступен. Это делает DELETE операцию не идемпотентной, но это общепринятый компромисс на тот случай, если ресурс был удален из базы данных, а не помечен, как удаленный [5].

Для прецедента «поиск мероприятия» был использован HTTP-Запросы GET

/webshedule/schedule/ в теле запроса, которого должен содержаться тип события и должно содержаться место или время. Для прецедента «получения информации о мероприятии» был использован HTTP-Запрос GET

/webshedule/schedule/{schedule_id}. Для прецедента «запрос списка мероприятий» был использован HTTP-Запрос GET /webshedule/schedules/ в теле запроса, которого должен содержаться тип события. Для прецедента «выбор мероприятия» для добавления в личное расписание был использован HTTP-Запрос GET /webshedule/schedule/ в теле запроса, которого должен содержаться тип события и обязательно должен быть один из параметров таких как время, факультет, преподаватель, группа. Для прецедента «выбор мероприятия» для добавления в личное расписание было использован HTTP-Запрос GET /webshedule/schedules/ в теле запроса, которого должен содержаться тип события и обязательно должен быть один из параметров таких как время, факультет, преподаватель, группа.

Для прецедента «Добавление нового мероприятия» был использован HTTP-Запрос POST

/webshedule/schedule/ в теле запроса, которого должен содержаться параметры мероприятия.

Для прецедента «Редактирование ранее созданного мероприятия» был использован HTTP-Запрос PUT/PUTCH

/webshedule/schedule/{schedule_id} в теле запроса, которого должен содержаться один из измененных параметров мероприятия, таких как преподаватель, локация, план мероприятия, время.

Для прецедента «Удаление мероприятия» был использован HTTP-Запрос DELETE

/webshedule/schedule/{ schedule_id}.

Для проектирования базы данных была разработана ER модель данных на рисунке 4. Далее представлено описание модели данных разработанной БД.

Для сервиса расписания выделены следующие сущности:

- Event - сущность представляет собой события, которые пользователь добавляет к себе в расписание.

- Class - сущность представляет класс события, который можно создать.

- Location - сущность представляет место, в котором можно провести мероприятия.

-Type_Location - сущность представляет тип места, в котором можно провести мероприятие.

- Building - сущность представляет корпус, в котором находится место проведения мероприятия.

- Type_Event - сущность представляет тип события, который можно создать.

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

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

- Faculty - сущность представляет факультет ВУЗа, который организовывает мероприятие.

- Group - сущность представляет группу ВУЗа, для которой организовывают мероприятие.

Логическая модель БД представлена на рис. 5.

Такая модель была выбрана в соответствии со стандартом iCalendar. iCalendar (по стандарту RFC5545) — это основной объект календаря и планирования, набор календаря и информации о расписании [9]. Формат файлов, который позволяет отправлять запросы на встречи и задачи с указанием даты и времени при помощи электронной почты или путем обмена файлами с расширением .ics.

Рис. 5. ER модель данных БД

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

Для работы с данными необходимыми для функционирования системы реализован REST API

сервисов с третьим уровнем зрелости API [10, 11], с помощью которого можно выполнять все CRUD-операции на таблице 1.

Таблица 1. Конечные точки API

HTTP-запрос Конечная точка Действие

GET / webshedule/user/ {userId} Получение пользователя по ГО

GET /webshedule/schedule/group/{groupId} Получение расписания по ГО группы

GET /webshedule/faculty/{facultyId} Получение факультета по ГО

GET /webshedule/faculties/ Получение коллекции факультетов

GET /webshedule/ group /{groupId} Получение группы по ГО

GET /webshedule/ groups/ Получение коллекции групп по ГО

POST / webshedule/ event/ Создание мероприятия

PUT / webshedule/ event/ {eventId} Изменение мероприятия по ГО

DELETE / webshedule/ event/ {eventId} Удаления мероприятия по ГО

Заключение

Применённая классическая модель разработки ПО, начиная с анализа требований, выбора архитектуры и проектирования модели позволила спроектировать API с 3 уровнями зрелости с разделением конечных точек по сервисам, соответствующим сущностям модели данных.

В результате разработан прототип сервиса для работы с расписанием ВГТУ, позволяющий показа расписания университета, использующее в качестве базы данных виртуальную, что дает возможность показа расписания в режиме реального времени, а также для создания/редактирования/удаления с

мероприятиями ВГТУ.

Проект доступен в репозитории github (https://github.com/pavelgulyev/microservices-events) для анализа и дальнейших исследований.

ЛИТЕРАТУРА

[1] gRPC vs REST, что выбрать для нового сервера? https://habr.com/ru/post/565020/.

[2] Сравнение архитектурных стилей API: SOAP vs REST vs GraphQL vs RPC. https://medium.com/nuances-of-programming/ сравнение-архитектурных-стилей-api-soap-vs-rest-vs-graphql-vs-rpc-68855deb3f4.

[3] Minakova, O.V., Akamsina, N.V., Deniskina, A. (2022). Designing Location-Based Microservice for University Activities. In: Solovev, D.B., Kyriakopoulos, G.L., Venelin, T. (eds) SMART Automatics and Energy. Smart Innovation, Systems and Technologies, vol 272. Springer, Singapore. https://doi.org/10.1007/978-981-16-8759-4_68

[4] Маслович, С.Ф. Разработка микросервиса отображения расписания занятий в университете / С.Ф. Маслович, Р.О. Сеглин // Вестник Вологодского государственного университета.

Серия: Технические науки. 2021. № 3(13). С. 27-29. EDN EDRMNE.

[5] Косс, Е.Н. Создание серверной части для автоматизации формирования расписания университета / Е.Н. Косс, К.А. Белеевский, А.М. Васецкий // Успехи в химии и химической технологии. 2021. Т. 35, № 10(245). С. 83-85. EDN JOZZOK. https://www.elibrary.ru/ item.asp?id=47193864

[6] Ивакин, Д.Ю. Автоматизация процесса предоставления расписания занятий за счёт использования rest API клиент-сервера / Д. Ю. Ивакин // Студенческая молодёжь XXI века: наука, творчество, карьера, цифровизация: Сборник материалов Межвузовской научно-практической конференции, Москва, 26 мая 2022 года / Под общей редакцией Е.А. Руднева, под научной редакцией Л.Н. Горбуновой. - Москва: Негосударственное образовательное частное учреждение высшего образования "Московский экономический институт", 2022. С. 235-244. EDN RLMUJD.

[7] REST APIs' Exhaustion Signs. https://www.programmersinc.com/over-fetching-and-under-fetching-rest-apis-exhaustion-signs/.

[8] HTTP Methods. https://restfulapi.net/http-methods/

[9] Internet Calendaring and Scheduling Core Object Specification (iCalendar). https://datatracker.ietf.org/doc/html/rfc5545#page-113 (дата обращения 23.02.2023). - Текст: электронный

[10] Understanding REST API Maturity Levels. https://www.programmersinc.com/over-fetching-and-under-fetching-rest-apis-exhaustion-signs/.

[11] Sandoval K. What Are Over-Fetching and Under-Fetching? Sandoval K; Ejior Nordic APIs. 1.03.2019. https://nordicapis.com/what-are-over-fetching-and-under-fetching/.

Павел Сергеевич Гуляев, студент кафедры систем управления и информационных технологий в строительстве ВГТУ E-mail: pavelgulyev@yandex.ru

Ольга Владимировна Минакова,

к.т.н., доцент кафедры систем управления и информационных технологий в строительстве ВГТУ E-mail: olgmina@gmail.com

Статья поступила 22.03.2023.

Experience in Designing API for the Schedule of University Events

P.S. Gulyaev, O.V. Minakova Voronezh State Technical University

Abstract: The paper presents a description of the API design process for creating an integration service of a university portal that provides information about events held at the university. In the course of the comparative analysis, the REST API was chosen. The development of the event schedule API was carried out using the classical software development methodology, including requirements analysis, justification of the choice of architecture, design of data models. A data model is described and substantiated that allows satisfying possible requests for extracting various information about events organized by the University. In the course of designing, a set of possible requests with a third level of maturity was substantiated and formed. The service prototype that supports the developed API is documented and implemented in the SpringBoot Framework. The working draft is available on github for discussion, evaluation and further development.

Keywords: software development, application programming interface, web service design, data model, event schedule, calendar

References

[1] gRPC vs REST, что выбрать для нового сервера? https://habr.com/ru/post/565020/.

[2] Comparison of architectural styles API: SOAP vs REST vs GraphQL vs RPC. https://medium.com/nuances-of-programming/ сравнение-архитектурных-стилей-api-soap-vs-rest-vs-graphql-vs-rpc-68855deb3f4.

[3] Minakova, O.V., Akamsina, N.V., Deniskina, A. (2022). Designing Location-Based Microservice for University Activities. In: Solovev, D.B., Kyriakopoulos, G.L., Venelin, T. (eds) SMART Automatics and Energy. Smart Innovation, Systems and Technologies, vol 272. Springer, Singapore. https://doi.org/10.1007/978-981-16-8759-4_68

[4] Maslovich, S.F. Razrabotka mikroservisa otobrazheniya raspisaniya zanyatiy v universitete / S.F. Maslovich, R.O. Seglin // Vestnik Vologodskogo gosudarstvennogo universiteta. Seriya: Tekhnicheskiye nauki. 2021. № 3(13). S. 27-29.EDN EDRMNE.

[5] Koss, Ye.N. Sozdaniye servernoy chasti dlya avtomatizatsii formirovaniya raspisaniya universiteta / Ye.N. Koss, K.A. Beleyevskiy, A.M. Vasetskiy //

Uspekhi v khimii i khimicheskoy tekhnologii. 2021. T. 35, № 10(245). S. 83-85. EDN JOZZOK. https://www.elibrary.ru/ item.asp?id=47193864

[6] Ivakin, D.YU. Avtomatizatsiya protsessa predostavleniya raspisaniya zanyatiy za schot ispol'zovaniya rest API kliyent-servera / D. YU. Ivakin // Studencheskaya molodozh' KHKHI veka: nauka, tvorchestvo, kar'yera, tsifrovizatsiya: Sbornik materialov Mezhvuzovskoy nauchno-prakticheskoy konferentsii, Moskva, 26 maya 2022 goda / Pod obshchey redaktsiyey Ye.A. Rudneva, pod nauchnoy redaktsiyey L.N. Gorbunovoy. - Moskva: Negosudarstvennoye obrazovatel'noye chastnoye uchrezhdeniye vysshego obrazovaniya "Moskovskiy ekonomicheskiy institut", 2022. S. 235-244. EDN RLMUJD.REST APIs' Exhaustion Signs. https://www.programmersinc.com/over-fetching-and-under-fetching-rest-apis-exhaustion-signs/.

[7] HTTP Methods. URL https://restfulapi.net/http-methods/

[8] Internet Calendaring and Scheduling Core Object Specification (iCalendar).

https://datatracker.ietf.org/doc/html/rfc5545#page-113 (дата обращения 23.02.2023). - Текст: электронный

[9] Understanding REST API Maturity Levels. https://www.programmersinc.com/over-fetching-and-under-fetching-rest-apis-exhaustion-signs/.

[10] Sandoval K. What Are Over-Fetching and Under-Fetching? Sandoval K; Блог Nordic APIs. 1.03.2019. https://nordicapis.com/what-are-over-fetching-and-under-fetching/.

Pavel Sergeevich Gulyaev, student of the Department of Control Systems and Information Technologies in Construction, VSTU E-mail: pavelgulyev@yandex.ru

Olga Vladimirovna Minakova,

Candidate of Technical Sciences, Associate Professor of the Department of Control Systems and Information Technologies in Construction, VSTU E-mail: olgmina@gmail.com

The paper has been received on 22/03/2023.