В чем разница между SpecFirst и CodeFirst, какие типичные ошибки делает аналитик при проектировании спецификации OpenAPI, как их исправить и зачем использовать POST вместо GET для получения данных с сервера в ответ на запрос клиента. Чек-лист, примеры и рекомендации.
9 типичных ошибок аналитика при разработке спецификации OpenAPI
Напомню, спецификация OpenAPI описывает ресурсы REST-приложения, маршруты обращения к ним и используемые при этом HTTP-методы, а также структуры данных полезной нагрузки запросов и ответов. Она описывает набор конечных точек сервера, к которым может обратиться клиент для реализации конкретных вариантов использования системы. При подходе SpecFirst (сначала спецификация) сперва разрабатывается спецификация, т.е. проектируется набор конечных точек (маршрут и HTTP-метод обращения к ресурсу), а также передаваемые данные. В случае подхода CodeFirst (сначала код) спецификация OpenAPI генерируется из исходного кода, например, с помощью фреймворка FASTAPI, пример работы с которым я показывала здесь. В сгенерированной с помощью CodeFirst спецификации ошибок будет меньше чем в той, которая сделана в рамках SpecFirst, т.к. в CodeFirst спецификация является выходом, а не входом. О том, какой из подходов лучше, можно долго спорить, однако, на практике реализации любого крупного проекта всегда предшествует этап проектирования. Для REST-приложения этот этап как раз может быть выполнен в виде разработки спецификации OpenAPI.
Полная спецификация OpenAPI включает следующие разделы:
- информационный раздел (info), включая описание (description), версию (version) и название (title);
- теги (tags) для разделения по пользовательским ролям или фичам продукта;
- маршруты (paths) с описанием ресурсов и HTTP-методов доступа к ним, а также содержимым заголовков и тела запросов (requestBody) и ответов (responses);
- статусы HTTP-ответов сервера на запросы клиента в подразделе responses;
- схемы данных (schemas) полезной нагрузки в теле ответа и запроса;
- схемы аутентификации (securitySchemes);
- метаданные (description или summary) и примеры (example) для контекстного описания тегов, запросов, ответов, их полей полезной нагрузки.
Разумеется, специализированные редакторы разработки спецификаций OpenAPI, например, Swagger в веб-сервисе SwaggerHub или editor-next.swagger.io, проверяют синтаксические ошибки в YAML-файле, компилируя документацию, которую можно визуально просмотреть в SwaggerUI. Однако, семантические ошибки редактор не проверяет, а именно их чаще всего совершают начинающие аналитики, когда описывают или проектируют API веб-приложения. Наиболее типичными из таких ошибок являются следующие:
- передача конфиденциальных данных в параметрах, отражаемых в маршруте /route/{param}, или строке GET-запроса, например, /route/?filter=filter_var;
- отсутствует аутентификация в запросах, которые ее предполагают, например, посмотреть перечень заявок на кредит может только пользователь с ролью Менеджер, а не все подряд;
- в клиентских запросах, которые предполагают наличие тела (POST, PUT, PATCH) этого тела нет, т.е. отсутствует полезная нагрузка с данными, которые надо передать от клиента серверу, поскольку он необходимы для вычислений, например, запрашиваемая сумма кредита, величина первоначального взноса и дополнительные комментарии, чтобы в ответ сервер сформировал набор кредитных предложений.
- дублирование одного и того же варианта использования по разным конечным точкам. Например, одобрить заявку и отклонить заявку – это один и тот же вариант использования системы — изменение статуса заявки, который может быть выполнен POST-запросом к маршруту /application/{id} с телом запроса, содержащим новый статус (approved или declined).
- схемы полезной нагрузки клиентских запросов и ответов сервера повторяются вместо повторного использования одного и того же описания через ссылку на объект с помощью $ref, содержимое которого описано в разделе схем;
- не описаны ответы сервера на клиентские запросы, включая HTTP-статусы по альтернативных путям, например, если ресурс отсутствует или сервер недоступен, т.е. в спецификации OpenAPI отсутствует подраздел response в описании конечной точки;
- отсутствуют метаданные (description, summary) и примеры (example) для контекстного описания тегов, запросов, ответов, их полей полезной нагрузки. Хотя это нельзя назвать ошибкой, наличие подобных комментариев упрощает понимание спецификации.
- вместо шаблонного описания ресурсов, например, /application/{id} в спецификации OpenAPI приведен набор частных случаев, например, /application/1, /application/2 и пр. Избежать этой ошибки поможет соглашение об именовании ресурсов REST-приложения, которое должно быть принято и понято всей командой, от аналитика до разработчика.
- названия ресурсов представлены не существительными, например, /application, /user и пр., а глаголами, например, /get_applications. Это нельзя назвать критичной ошибкой, однако такое именование не соответствует наиболее распространенному стилю именования ресурсов в REST-приложениях. Аналогично предыдущему пункту, при наличии общего соглашения об именовании ресурсов REST-приложения вероятность сделать такую ошибку сильно снижается.
Далее рассмотрим первую из перечисленных ошибок, связанную с небезопасной реализацией фильтров через GET-запрос.
Основы архитектуры и интеграции информационных систем
Код курса
OAIS
Ближайшая дата курса
20 января, 2025
Продолжительность
16 ак.часов
Стоимость обучения
36 000 руб.
Небезопасная фильтрация: передача конфиденциальных данных или почему не нужно использовать GET там, где нужен POST
Многие начинающие аналитики ошибочно считают, что в REST-приложениях для получения данных используются только GET-запросы. Однако не стоит однозначно натягивать CRUD-операции на HTTP-глаголы, поскольку сами по себе методы протокола HTTP не выполняют никаких действий на сервере. Рассмотрим пример с получением данных, отфильтрованных по какому-то признаку. Например, необходимо получить данные о персональных предложениях, сформированных для конкретного пользователя. Если реализовать этот вариант использования через GET-запрос, придется передавать данные пользователя в параметрах, отражаемых в маршруте /product/3435689, или строке GET-запроса, например, /product/?name=Иванов+Иван_Иванович. Это небезопасно, поскольку GET-запросы кэшируются, а строка URL-адреса, по которому идет обращение клиента к серверу, может сохраняться в истории браузера. Разумеется, конфиденциальными данными могут быть не только персональные данные согласно определению из 152-ФЗ, такие как ФИО, номер паспорта или СНИЛС, но и другие чувствительные данные, которые не должны быть раскрыты, например, внутренний идентификатор пользователя в корпоративной системе. Если фильтрация предполагает использование чувствительных к раскрытию данных, их следует передавать в теле POST-запроса, которое шифруется при использовании протокола HTTPS и не кэшируется, в отличие GET-запроса.
Разумеется, в этой небольшой статье охвачены не все возможные ошибки, которые можно сделать при разработке спецификации OpenAPI. Однако, надеюсь, этот небольшой чек-лист поможет вам сократить количество переделок при проектировании веб-приложений.
Основы архитектуры и интеграции информационных систем
Код курса
OAIS
Ближайшая дата курса
20 января, 2025
Продолжительность
16 ак.часов
Стоимость обучения
36 000 руб.
Подробнее познакомиться со всеми рассмотренными темами, а также другими основами архитектуры и интеграции информационных систем вам помогут мои курсы Школы прикладного бизнес-анализа в нашем лицензированном учебном центре обучения и повышения квалификации системных и бизнес-аналитиков в Москве:
