Проектирование API для системных аналитиков

Основы интеграции: архитектурные стили REST, SOAP, GraphQL и gRPC

Добро пожаловать на курс «Проектирование API для системных аналитиков». Это первая статья нашего цикла, и мы начнем с фундамента. Прежде чем учиться проектировать стены и крышу, нужно разобраться, на каком фундаменте будет стоять наше здание.

В мире системного анализа API (Application Programming Interface) — это не просто набор технического кода, а способ общения между программами. Как аналитик, вы должны понимать, на каком «языке» системы будут разговаривать друг с другом. Сегодня мы разберем четыре главных архитектурных стиля: SOAP, REST, GraphQL и gRPC.

Что такое API и зачем нам стили?

Представьте, что вы пришли в ресторан. Вы (клиент) хотите заказать еду, которая находится на кухне (сервер). Вы не можете просто зайти на кухню и начать готовить. Вам нужен посредник — официант. В мире IT этим официантом является API.

!Аналогия работы API через образ ресторана, где официант передает заказ от клиента к кухне.

Однако официанты бывают разные. В одном ресторане принято писать заказ на бумажке строго по форме (SOAP), в другом — просто называть блюда (REST), в третьем — вы можете собрать свой салат из ингредиентов (GraphQL), а в четвертом — заказ передается мгновенно через гарнитуру (gRPC).

Разберем каждый из этих подходов подробнее.

SOAP: Строгий корпоративный стандарт

SOAP (Simple Object Access Protocol) — это ветеран интеграций. Он появился в конце 90-х и до сих пор активно используется в крупных корпорациях, банках и государственных системах.

Особенности SOAP

Протокол, а не стиль. SOAP — это строгий протокол. У него есть жесткие правила, которые нельзя нарушать.

Формат XML. Все сообщения передаются исключительно в формате XML.

Контракт WSDL. У SOAP есть «паспорт» — файл WSDL (Web Services Description Language). Это документ, который описывает все методы, типы данных и форматы запросов. Если запрос не соответствует WSDL, он будет отвергнут.

Аналогия

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

Когда использовать?

* Финтех и банковские системы (где важна транзакционность и безопасность). * Государственные интеграции. * Системы, требующие строгой типизации и формальных контрактов.

REST: Гибкость и простота

REST (Representational State Transfer) — это архитектурный стиль, который стал стандартом де-факто для веб-разработки. Большинство публичных API (Google, Twitter, YouTube) построены на REST.

Особенности REST

Ресурсы. В центре внимания — «ресурс» (сущность). Например: Пользователь, Заказ, Товар.

HTTP-методы. Для управления ресурсами используются глаголы протокола HTTP:

* GET — получить данные. * POST — создать новые данные. * PUT / PATCH — обновить данные. * DELETE — удалить данные.

Stateless (Без состояния). Сервер не запоминает состояние клиента между запросами. Каждый запрос должен содержать всю необходимую информацию.

Формат JSON. Хотя REST может работать и с XML, стандартом стал легкий и читаемый JSON.

!Схема обмена сообщениями в REST API с использованием HTTP методов и JSON.

Проблема REST: Over-fetching и Under-fetching

Представьте, что вам нужно узнать только имя пользователя, но REST API возвращает вам огромный объект с его адресом, историей заказов и размером обуви. Это Over-fetching (избыточные данные). Или наоборот: чтобы показать профиль, вам нужно сделать три разных запроса (за пользователем, за его фото и за его друзьями). Это Under-fetching (недостаток данных в одном запросе).

GraphQL: Клиент решает всё

Чтобы решить проблемы REST, компания Facebook (Meta) разработала GraphQL. Это язык запросов к API.

Особенности GraphQL

Один эндпоинт. В отличие от REST, где много адресов (/users, /orders), в GraphQL всего один адрес (обычно /graphql).

Точность. Клиент сам говорит серверу, какие поля ему нужны. Хочешь только имя? Получишь только имя.

Вложенность. Можно одним запросом получить пользователя, его друзей и их последние посты.

Аналогия

Вы приходите в буфет (шведский стол). Вам не дают готовое блюдо «как есть». Вы берете тарелку и кладете туда ровно столько картошки и мяса, сколько хотите съесть. Ничего лишнего.

Пример запроса GraphQL

В ответ придет только JSON с полями name и email.

gRPC: Скорость и эффективность

gRPC (Google Remote Procedure Call) — это современный фреймворк для высокопроизводительных систем, разработанный Google.

Особенности gRPC

Protocol Buffers (Protobuf). Вместо текстового JSON используется бинарный формат. Данные сжимаются в байты, что делает передачу невероятно быстрой.

HTTP/2. Работает поверх современного протокола HTTP/2, который поддерживает двунаправленные потоки (стриминг).

Строгая типизация. Как и в SOAP, здесь есть контракт (файл .proto), описывающий структуру данных.

Аналогия

Если REST — это разговор двух людей по телефону, то gRPC — это обмен зашифрованными телеграммами между двумя шпионами. Это непонятно для посторонних (бинарный формат), но передается мгновенно и занимает минимум места.

Когда использовать?

* Микросервисная архитектура (общение сервисов внутри компании). * Системы реального времени (стриминг видео, игры). * Мобильные приложения с плохим интернетом (экономия трафика).

Сводная таблица сравнения

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

| Характеристика | SOAP | REST | GraphQL | gRPC | | :--- | :--- | :--- | :--- | :--- | | Формат данных | XML | Чаще всего JSON | JSON | Protobuf (бинарный) | | Протокол | Любой (SMTP, HTTP) | HTTP 1.1 | HTTP 1.1 | HTTP/2 | | Сложность | Высокая | Низкая/Средняя | Средняя | Средняя/Высокая | | Кэширование | Сложно | Отлично (средствами HTTP) | Сложно | Сложно | | Читаемость | Человеко-читаемый (но громоздкий) | Человеко-читаемый | Человеко-читаемый | Нечитаемый (бинарный) | | Главный плюс | Надежность и стандарты | Простота и популярность | Гибкость выборки данных | Производительность |

Заключение

Не существует «лучшего» стиля API. Существует стиль, подходящий под ваши требования.

* Нужна интеграция с банком? Скорее всего, это SOAP. * Делаете публичное API для сайта? Выбирайте REST. * У вас сложное приложение со множеством связей (соцсеть)? Смотрите в сторону GraphQL. * Строите высоконагруженные микросервисы? Ваш выбор — gRPC.

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

Проектирование REST API: ресурсы, HTTP-методы и коды ответов

Рад видеть вас снова на курсе «Проектирование API для системных аналитиков». В прошлой статье мы рассмотрели фундамент интеграций и сравнили четыре архитектурных стиля. Мы выяснили, что REST (Representational State Transfer) является самым популярным выбором для веб-сервисов благодаря своей простоте и гибкости.

Сегодня мы переходим от теории к практике. Мы научимся проектировать REST API так, чтобы разработчики говорили вам «спасибо», а пользователи не страдали от ошибок. Мы разберем три кита, на которых стоит REST: Ресурсы, Методы и Коды ответов.

Ресурсо-ориентированный подход

Главная ошибка новичков при проектировании REST API — мыслить действиями (глаголами). В классическом программировании (RPC) мы привыкли вызывать функции: getUser(), calculatePrice(), deleteOrder(). В REST мы должны перевернуть свое мышление и начать мыслить существительными.

В мире REST всё является ресурсом. Пользователь — это ресурс. Заказ — это ресурс. Комментарий — это ресурс.

Правила именования ресурсов (URI)

Адрес, по которому доступен ресурс, называется URI (Uniform Resource Identifier). Хороший дизайн URI должен быть интуитивно понятным.

!Анатомия REST-запроса: от протокола до конкретного ресурса

Вот золотые правила именования путей (эндпоинтов):

Используйте существительные, а не глаголы.

* ~~Плохо:~~ /getUsers, /createNewOrder, /updateProduct * Хорошо: /users, /orders, /products

Используйте множественное число.

Это вопрос договоренностей, но стандарт индустрии — множественное число. Это логично, так как /users — это коллекция всех пользователей, а /users/15 — конкретный элемент этой коллекции. * ~~Плохо:~~ /user/15, /category/electronics * Хорошо: /users/15, /categories/electronics

Используйте иерархию для вложенных ресурсов.

Если ресурс не может существовать без родителя, отразите это в пути. Например, заказ принадлежит пользователю. * Пример: /users/15/orders (получить все заказы пользователя с ID 15). * Пример: /users/15/orders/3 (получить заказ №3 пользователя №15).

Kebab-case для составных названий.

В URL не принято использовать нижнее подчеркивание или CamelCase. * ~~Плохо:~~ /productCategories, /product_categories * Хорошо: /product-categories

HTTP-методы: Глаголы нашего языка

Если URL — это существительные, то действия над ними мы выражаем через HTTP-методы. Это глаголы, которые говорят серверу, что именно мы хотим сделать с ресурсом.

Основные методы, которые должен знать аналитик:

1. GET — Получение данных

Самый частый запрос. Используется только для чтения. * Безопасный: Не изменяет данные на сервере. * Идемпотентный: Сколько бы раз вы ни вызвали GET /users, результат (состояние сервера) не изменится.

2. POST — Создание данных

Используется для создания нового ресурса. * Пример: Отправляем JSON с данными пользователя на /users, сервер создает запись и возвращает её ID. * Не идемпотентный: Если вы отправите один и тот же запрос POST 5 раз, вы создадите 5 одинаковых пользователей (если нет ограничений на уникальность).

3. PUT — Полное обновление

Используется, когда мы хотим полностью заменить ресурс по конкретному ID. * Логика: «Возьми этот объект и положи его вместо старого». Если вы передадите в PUT только имя пользователя, а остальные поля (email, возраст) не укажете, они могут затереться (стать null), так как PUT подразумевает полную замену.

4. PATCH — Частичное обновление

Используется для точечного изменения. * Логика: «Поменяй только те поля, которые я прислал». Если вы хотите сменить только пароль, используйте PATCH.

5. DELETE — Удаление

Удаляет указанный ресурс.

> Важное замечание: Никогда не используйте GET для изменения данных (например, GET /deleteUser?id=1). Это грубейшее нарушение безопасности и стандартов. Поисковые роботы или кэширующие прокси могут случайно «прокликать» такие ссылки и удалить ваши данные.

!Связь бизнес-операций с техническими методами HTTP

Коды ответов: Обратная связь

Когда сервер обработал (или не смог обработать) запрос, он обязан вернуть HTTP Status Code. Это трехзначное число, которое сообщает клиенту о результате.

Для аналитика важно не просто написать «сервер возвращает ошибку», а указать конкретный код. Коды делятся на классы:

* 2xx — Успех (Success) * 3xx — Перенаправление (Redirection) * 4xx — Ошибка клиента (Client Error) * 5xx — Ошибка сервера (Server Error)

Разберем самые важные коды, которые вы будете использовать в 90% случаев.

Успешные коды (2xx)

* 200 OK. Универсальный код успеха. Используется для синхронных запросов (GET, PUT, PATCH). * 201 Created. Ресурс успешно создан. Обязателен в ответ на POST. Обычно сервер также возвращает заголовок Location со ссылкой на созданный ресурс. * 204 No Content. Успешно, но возвращать нечего. Часто используется для DELETE или PUT, когда клиенту не нужно тело ответа, достаточно знать, что все прошло хорошо.

Ошибки клиента (4xx)

Это значит, что клиент (фронтенд или другая система) отправил что-то не то. Вина на стороне отправителя.

* 400 Bad Request. Общая ошибка валидации. Например, пропущено обязательное поле, неверный формат email или JSON «битый». * 401 Unauthorized. «Я тебя не знаю». Пользователь не авторизован (не передал токен или пароль). * 403 Forbidden. «Я знаю, кто ты, но тебе сюда нельзя». Пользователь авторизован, но у него нет прав на это действие (например, менеджер пытается удалить администратора). * 404 Not Found. Ресурс не найден. Например, запрос /users/9999, а такого пользователя нет.

Ошибки сервера (5xx)

Это значит, что запрос был корректным, но сервер сломался. Вина на стороне разработчиков бэкенда.

* 500 Internal Server Error. «Что-то пошло не так». Самая частая ошибка, когда в коде случается необработанное исключение (NullPointerException и т.д.). * 503 Service Unavailable. Сервер перегружен или находится на обслуживании.

Параметры запроса: Path vs Query

Часто возникает вопрос: как передавать параметры? В пути (Path) или в строке запроса (Query)?

Path Parameters (Параметры пути)

Используются для идентификации конкретного ресурса. Они являются частью адреса. * Пример: GET /users/123 * Здесь 123 — это ID ресурса. Без него запрос GET /users/ вернет список, а не конкретного человека. Это обязательный параметр для доступа к сущности.

Query Parameters (Параметры строки запроса)

Используются для сортировки, фильтрации, пагинации. Они идут после знака ?. * Пример: GET /users?role=admin&sort=name * Здесь мы говорим: «Дай мне пользователей, но не всех, а только админов, и отсортируй их по имени». Если убрать эти параметры, запрос все равно останется валидным, просто вернет список по умолчанию.

Пример проектирования эндпоинта

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

Задача: Создать товар, получить информацию о нем и изменить цену.

1. Создание товара

* Метод: POST * URL: /products * Тело запроса (Body): * Успешный ответ: 201 Created

2. Получение товара

* Метод: GET * URL: /products/{id} (например, /products/55) * Успешный ответ: 200 OK + JSON с данными товара. * Ошибка: 404 Not Found (если товара с ID 55 нет).

3. Изменение цены

Мы меняем только одно поле, поэтому логичнее использовать PATCH. * Метод: PATCH * URL: /products/55 * Тело запроса: * Успешный ответ: 200 OK (с обновленным объектом) или 204 No Content.

Заключение

Проектирование REST API — это искусство называть вещи своими именами. Правильно подобранные ресурсы, методы и коды ответов делают интеграцию интуитивной и предсказуемой.

Запомните главные принципы:

URL — это существительные.

HTTP-методы — это глаголы.

Коды ответов — это результат операции.

В следующей статье мы поговорим о том, как документировать наши API, чтобы разработчики не задавали лишних вопросов. Мы разберем спецификацию OpenAPI (Swagger) и научимся описывать контракты.

Работа с данными: форматы JSON/XML, заголовки и идемпотентность запросов

Приветствую вас на третьем занятии курса «Проектирование API для системных аналитиков». Мы уже заложили фундамент, разобравшись с архитектурными стилями, и научились правильно именовать ресурсы и методы. Теперь пришло время заглянуть внутрь посылки, которую мы отправляем серверу.

Представьте, что вы отправляете посылку другу. Вы выбрали службу доставки (HTTP) и указали адрес (URI). Но что лежит внутри коробки? Как упаковано содержимое? И что написано на наклейках поверх коробки? Сегодня мы поговорим именно об этом: о форматах данных, служебных заголовках и важнейшем понятии надежности систем — идемпотентности.

Форматы передачи данных: JSON против XML

В системном анализе важно точно определить, как именно данные будут структурированы при передаче. Два самых популярных формата — это JSON и XML. Давайте разберем их анатомию.

JSON (JavaScript Object Notation)

На сегодняшний день это стандарт де-факто для REST API. Он легкий, понятный человеку и легко разбирается (парсится) машинами.

Структура JSON:

Объекты: Обозначаются фигурными скобками {}. Это неупорядоченный набор пар «ключ: значение».

Массивы: Обозначаются квадратными скобками []. Это упорядоченный список значений.

Типы данных: Строки, числа, булевы значения (true/false), null, объекты и массивы.

!Визуальное представление того, как реальный объект преобразуется в формат JSON.

Пример описания пользователя в JSON:

Преимущества JSON: * Компактность (меньше символов, чем в XML). * Нативная поддержка в браузерах и JavaScript. * Высокая читаемость.

XML (eXtensible Markup Language)

Более старый, строгий и мощный формат. Он похож на HTML, так как использует теги. XML часто встречается в банковской сфере, в протоколе SOAP и в устаревших (legacy) системах.

Структура XML: Вместо фигурных скобок здесь используются открывающие и закрывающие теги. Данные могут храниться как внутри тегов, так и в атрибутах.

Тот же пример пользователя в XML:

Преимущества XML: * Схемы (XSD): Позволяют очень строго валидировать структуру документа (например, требовать, чтобы поле zip состояло ровно из 6 цифр). * Пространства имен: Позволяют избегать конфликтов имен тегов при объединении разных документов.

Что выбрать аналитику?

Если вы проектируете современное REST API для мобильного приложения или веб-сайта — выбирайте JSON. Если вы интегрируетесь с крупной государственной системой или банком, где требуются строгие контракты и цифровая подпись документов — вам, скорее всего, придется работать с XML.

HTTP-заголовки: Метаданные посылки

Помимо самих данных (тела запроса), HTTP-запрос содержит заголовки (Headers). Это служебная информация, которая говорит серверу (или клиенту), как обрабатывать сообщение.

Представьте наклейки на почтовом конверте: «Осторожно, хрупкое», «Авиапочта», «Отправить уведомление о вручении». Это и есть заголовки.

Ключевые заголовки для аналитика

Content-Type

Самый важный заголовок при работе с данными. Он сообщает получателю, в каком формате пришло тело сообщения. Если вы отправляете JSON, вы обязаны указать: Content-Type: application/json Если сервер получит JSON, но заголовок будет text/plain, он может не понять, как его прочитать.

Accept

Используется для Content Negotiation (согласования контента). Клиент говорит серверу: «Я понимаю только эти форматы, пришли мне ответ в одном из них». Пример: Accept: application/json — клиент просит вернуть данные в JSON.

Authorization

Здесь передаются данные для аутентификации. Чаще всего это токен. Пример: Authorization: Bearer eyJhbGciOiJIUz...

User-Agent

Информация о клиенте (браузер, мобильное приложение, бот). Помогает серверу собирать статистику или адаптировать ответ.

X-Correlation-ID (или X-Request-ID)

Это кастомный (нестандартный) заголовок, который крайне важен для отладки в микросервисах. Это уникальный идентификатор цепочки запросов. Если пользователь нажал кнопку, и этот запрос прошел через 5 микросервисов, везде должен фигурировать один и тот же ID. По нему аналитики и разработчики ищут логи в Kibana или Splunk.

Идемпотентность: Защита от дублей

Переходим к одной из самых сложных, но важных концепций для проектирования надежных API. Это идемпотентность.

В математике операция считается идемпотентной, если её многократное применение дает тот же результат, что и однократное. Это можно записать формулой:

Где — это функция (операция), а — исходное состояние. Это означает, что повторный вызов функции к результату первого вызова ничего не меняет.

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

Почему это важно? Проблема «Двойного списания»

Представьте ситуацию:

Клиент (мобильное приложение) отправляет POST /payments (списать 1000 рублей).

Сервер списывает деньги.

Сервер отправляет ответ «ОК».

Сбой сети! Ответ не доходит до клиента.

Клиент думает, что запрос потерялся, и автоматически (или по нажатию пользователя) отправляет тот же запрос повторно.

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

!Иллюстрация того, как сетевой сбой может привести к дублированию операций при отсутствии идемпотентности.

Идемпотентность HTTP-методов

При проектировании API вы должны знать, какие методы являются идемпотентными по стандарту:

* GET (Идемпотентный): Сколько бы раз вы ни запросили список товаров, список товаров от этого не изменится (сам факт чтения не меняет данные). * PUT (Идемпотентный): Метод PUT полностью заменяет ресурс. Если вы 10 раз отправите «Установи имя пользователя = Иван», в итоге имя будет «Иван». Состояние системы после 1-го и 10-го запроса одинаковое. * DELETE (Идемпотентный): Если вы удалили заказ №5, он исчез. Если вы попытаетесь удалить его снова, он все еще удален (даже если сервер вернет 404, состояние системы не изменилось — заказа нет). * POST (НЕ Идемпотентный): Метод POST создает новый ресурс. 10 запросов POST /orders создадут 10 разных заказов.

Как сделать POST идемпотентным?

Аналитик должен предусмотреть механизм защиты. Самый популярный способ — использование заголовка Idempotency-Key.

Алгоритм работы:

Клиент генерирует уникальный ключ (например, UUID) перед отправкой запроса: Idempotency-Key: 123-abc.

Клиент отправляет POST запрос с этим заголовком.

Сервер проверяет: «Видел ли я уже ключ 123-abc?».

* Нет: Выполняет операцию, сохраняет результат и ключ в базе. Возвращает ответ. * Да: Не выполняет операцию повторно! Просто возвращает тот же самый ответ, который вернул в первый раз.

Таким образом, даже при обрыве связи повторный запрос с тем же ключом не приведет к двойному списанию.

Заключение

Сегодня мы углубились в технические детали передачи данных. Мы выяснили, что:

JSON — лучший друг современного аналитика, но про XML забывать нельзя.

Заголовки управляют тем, как сервер понимает наши данные (Content-Type) и кто мы такие (Authorization).

Идемпотентность — это страховка от сетевых сбоев. Особенно важно проектировать её для финансовых операций и метода POST.

В следующей, заключительной статье нашего цикла, мы научимся документировать всё это. Мы разберем спецификацию OpenAPI (Swagger) и узнаем, как превратить ваши требования в красивую и понятную документацию для разработчиков.

Документирование API: спецификация OpenAPI и инструменты Swagger

Приветствую вас на четвертом занятии курса «Проектирование API для системных аналитиков». Мы проделали большой путь: разобрали архитектурные стили (REST, SOAP, gRPC), научились проектировать ресурсы и методы, а также упаковывать данные в JSON.

Но представьте ситуацию: вы спроектировали идеальное API. У вас в голове есть четкая картина: какие эндпоинты существуют, какие поля обязательны, какие коды ошибок возвращаются. Вы передаете задачу разработчику. Проходит неделя, и вы видите результат: поля названы иначе, типы данных перепутаны, а вместо 404 ошибки возвращается 200 с текстом «Ничего не найдено».

Почему так произошло? Потому что не было контракта. Сегодня мы поговорим о том, как зафиксировать ваши требования так, чтобы их поняли и люди, и машины. Мы изучим стандарт OpenAPI и экосистему инструментов Swagger.

Проблема «Испорченного телефона»

Раньше документация к API писалась в Word или Confluence. Аналитик создавал табличку:

> «Метод GET /users принимает ID и возвращает пользователя».

Этого недостаточно. Разработчик фронтенда спросит: «А ID — это число или строка?», «А поле email будет всегда или может быть null?», «А какой формат даты?».

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

Решением стала концепция Machine-readable documentation (машиночитаемая документация). Это файл, который описывает API по строгим правилам.

OpenAPI vs Swagger: В чем разница?

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

* OpenAPI Specification (OAS) — это стандарт (спецификация). Это набор правил, описывающий, как должен выглядеть файл документации. Это как правила грамматики русского языка. * Swagger — это набор инструментов (программ), которые работают с этим стандартом. Это как текстовый редактор Word или Google Docs, в котором вы пишете текст по правилам языка.

История вопроса: В 2010 году компания SmartBear создала спецификацию Swagger. В 2015 году они передали её под управление Linux Foundation, и спецификацию переименовали в OpenAPI. Однако инструменты (редактор, генератор кода) остались под брендом Swagger.

!Экосистема OpenAPI: спецификация в центре, инструменты вокруг.

Структура спецификации OpenAPI

Документ OpenAPI — это обычно файл в формате YAML или JSON. Мы будем использовать YAML, так как он намного легче читается человеком. В нем используются отступы вместо скобок.

Файл спецификации состоит из нескольких ключевых секций. Давайте разберем их на примере API нашего интернет-магазина.

1. Info (Общая информация)

Здесь мы пишем, что это за API, его версию и контакты создателей.

2. Servers (Серверы)

Здесь указываются адреса, где доступно API. Это позволяет тестировщикам переключаться между тестовым и продуктовым контуром прямо в документации.

3. Paths (Пути и методы)

Это сердце документации. Здесь описываются все ресурсы (эндпоинты) и методы (GET, POST и т.д.).

Для каждого метода мы должны описать:

Summary: Краткое описание действия.

Parameters: Входные параметры (в пути, в строке запроса или в заголовках).

Responses: Возможные ответы сервера (коды и тела ответов).

Пример описания получения товара по ID:

yaml components: schemas: Product: type: object required: - id - name - price properties: id: type: integer format: int64 example: 101 name: type: string example: "iPhone 15" price: type: number format: double example: 999.99 isAvailable: type: boolean description: Доступен ли товар для заказа default: true ``

Инструменты Swagger

Теперь, когда мы понимаем структуру файла, давайте посмотрим, где его писать и как использовать.

Swagger Editor

Это редактор, который делит экран на две части. Слева вы пишете код на YAML, а справа в реальном времени видите красивую документацию. Если вы допустите ошибку в отступах, редактор сразу подсветит её красным.

Swagger UI

Это то, что видит конечный пользователь (разработчик). Это веб-страница, сгенерированная из вашего YAML-файла.

Главная фишка Swagger UI — интерактивность. Кнопка «Try it out» позволяет отправить реальный запрос к API прямо из документации. Не нужно открывать Postman или писать код. Вы вводите параметры в форму, нажимаете «Execute» и видите реальный ответ сервера.

!Интерактивная документация Swagger UI позволяет тестировать запросы прямо в браузере.

Swagger Codegen

Это инструмент для ленивых (в хорошем смысле) разработчиков. Он берет ваш файл OpenAPI и автоматически генерирует код.

* Для бэкенда: Генерирует «скелет» сервера (контроллеры, модели). Разработчику остается только написать бизнес-логику. * Для фронтенда: Генерирует клиентскую библиотеку. Фронтендеру не нужно вручную создавать классы для каждого запроса.

Подход Design-First

В системном анализе существует два подхода к созданию API:

Code-First (Сначала код). Разработчик пишет код, ставит аннотации над методами, и документация генерируется автоматически.

Минус:* Документация часто получается «технической», без описаний, и аналитик не контролирует процесс.

Design-First (Сначала дизайн). Аналитик пишет спецификацию OpenAPI до того, как написана первая строчка кода.

Плюс:* Это настоящий контракт. Фронтенд и бэкенд могут работать параллельно. Фронтенд делает заглушки (mock) на основе спецификации, пока бэкенд пишет логику.

Для системного аналитика Design-First — это профессиональный стандарт. Вы проектируете интерфейс взаимодействия, утверждаете его с командой, и только потом начинается разработка.

Типы данных в OpenAPI

OpenAPI поддерживает базовые типы данных, которые маппятся на типы в языках программирования:

* integer (целые числа) — форматы int32, int64. * number (дробные числа) — форматы float, double. * string (строки) — форматы date, date-time, password, byte (base64). * boolean (true/false).

Также есть массивы (type: array) и объекты (type: object).

Важно: Всегда указывайте example` (пример) для полей. Это сильно упрощает жизнь тем, кто будет читать вашу документацию.

Заключение

Документирование API через OpenAPI — это не просто написание «инструкции». Это создание строгого контракта, который является единственным источником правды для всей команды разработки.

Используя OpenAPI, вы:

Устраняете разночтения между аналитикой, бэкендом и фронтендом.

Позволяете тестировать API до его разработки.

Автоматизируете рутину (генерация кода и тестов).

В следующей статье мы перейдем к теме, которая волнует всех: Безопасность API. Мы разберем, что такое Basic Auth, API Keys, JWT токены и OAuth 2.0, и как защитить наши данные от злоумышленников.

Безопасность, версионирование и управление ошибками в API

Добро пожаловать на финальную лекцию курса «Проектирование API для системных аналитиков». Мы прошли долгий путь: выбрали архитектурный стиль (REST, gRPC или GraphQL), научились проектировать ресурсы, упаковывать данные в JSON и описывать контракты с помощью OpenAPI.

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

Сегодня мы поговорим о трех столпах, которые превращают просто работающий код в профессиональный продукт: Безопасность, Версионирование и Управление ошибками.

Безопасность API: Замки и ключи

Безопасность — это не просто «пароль». Для системного аналитика важно разделять два фундаментальных понятия, которые часто путают: Аутентификация и Авторизация.

Аутентификация vs Авторизация

Аутентификация (Authentication, AuthN): Ответ на вопрос «Кто ты?». Это проверка паспорта на проходной. Система проверяет, что пользователь именно тот, за кого себя выдает.

Авторизация (Authorization, AuthZ): Ответ на вопрос «Что тебе можно делать?». Это пропуск в конкретные зоны. Даже если вы сотрудник (прошли аутентификацию), вам может быть запрещен вход в серверную (нет авторизации).

Разберем основные механизмы, которые вы будете закладывать в требования.

1. Basic Authentication

Самый старый и простой способ. Клиент отправляет логин и пароль с каждым запросом в заголовке Authorization. Данные кодируются в Base64.

> Важно: Base64 — это не шифрование! Это просто другой способ записи. Строку в Base64 может раскодировать любой школьник. Поэтому Basic Auth можно использовать только поверх защищенного соединения HTTPS (TLS).

2. API Keys (API-ключи)

Вы выдаете клиенту длинную уникальную строку (ключ). Клиент передает её в заголовке (например, X-API-Key: abc123xyz).

* Плюс: Простота. * Минус: Если ключ украдут, злоумышленник получит полный доступ. Ключи обычно не имеют срока действия.

3. JWT (JSON Web Tokens)

Это современный стандарт для REST API. Идея в том, что сервер не запоминает сессию пользователя (Stateless). Вместо этого сервер выдает пользователю «удостоверение с печатью» — токен.

Токен состоит из трех частей, разделенных точками: Header.Payload.Signature.

!Анатомия JSON Web Token: три компонента, обеспечивающие передачу данных и проверку подлинности.

Самая важная часть — это Подпись (Signature). Она гарантирует, что данные внутри токена не были изменены. Математически это выглядит так:

Где: * — итоговая подпись (Signature), которая добавляется в конец токена. * — криптографическая функция хеширования, использующая алгоритм SHA-256 и секретный ключ. * — закодированный заголовок (Header), содержащий тип токена и алгоритм. * — закодированная полезная нагрузка (Payload), содержащая данные пользователя (ID, роль). * — секретный ключ, который знает только сервер.

Если злоумышленник изменит в Payload роль с user на admin, хеш изменится. Сервер проверит подпись, увидит несовпадение и отвергнет токен.

4. OAuth 2.0

Это не просто токен, а целый протокол делегирования доступа.

Аналогия: Вы приехали в отель и отдаете машину парковщику. Вы не даете ему свои ключи от дома и сейфа (ваш пароль). Вы даете ему «ключ парковщика» (Access Token), который позволяет только завести машину и проехать 50 метров, но не открыть багажник.

OAuth 2.0 используется, когда вы видите кнопки «Войти через Google» или «Войти через Facebook».

Версионирование: Эволюция без боли

API — это живой организм. Бизнес-требования меняются, и вам нужно менять API. Но у вашего API уже есть потребители (мобильные приложения, партнеры). Если вы просто измените формат ответа, их приложения сломаются.

Breaking Changes (Ломающие изменения)

Аналитик обязан отличать ломающие изменения от неломающих.

* Неломающее изменение: Добавление нового поля в JSON-ответ или добавление нового необязательного фильтра. Старые клиенты просто проигнорируют новое поле. * Ломающее изменение: Удаление поля, переименование поля, изменение типа данных (была строка, стало число), добавление нового обязательного параметра.

Если изменение ломающее, нужно вводить новую версию API.

Стратегии версионирования

#### 1. Версионирование в URI (Самое популярное) Вы явно указываете версию в пути к ресурсу.

* GET /v1/users * GET /v2/users

Плюсы: Наглядно, легко кэшировать, легко тестировать в браузере. Минусы: С точки зрения философии REST, v1/users и v2/users — это разные ресурсы, хотя по факту это одни и те же люди.

#### 2. Версионирование через Query-параметр

* GET /users?version=2

Плюсы: URL ресурса остается неизменным. Минусы: Сложнее настраивать кэширование.

#### 3. Версионирование через заголовки (Header) Клиент передает версию в служебном заголовке.

* Accept-Version: v2

Плюсы: URL остается чистым (/users). Минусы: Сложно тестировать (нужны плагины или Postman), не видно версию визуально в адресной строке.

> Совет аналитику: Если вы не знаете, что выбрать — выбирайте URI Versioning (/v1/). Это стандарт де-факто для большинства публичных API (Stripe, Twitter, Google).

Управление ошибками: Больше, чем просто код 500

В статье про REST мы обсуждали коды ответов (200, 400, 500). Но одного кода мало. Если клиент получает 400 Bad Request, он должен понять, что именно не так.

Проблема «Разных ошибок»

Без стандартов разработчики начинают изобретать велосипеды: * Один вернет: {"error": "Invalid email"} * Другой: {"message": "Email is wrong", "code": 105} * Третий: {"success": false, "description": "Bad email"}

Фронтенду приходится писать отдельные обработчики под каждый микросервис.

Решение: RFC 7807 (Problem Details)

Существует стандарт IETF, описывающий, как должны выглядеть ошибки в JSON. Формат называется Problem Details for HTTP APIs.

Пример правильного ответа с ошибкой:

Основные поля: * type: Ссылка на документацию с описанием типа ошибки. * title: Краткое, понятное человеку название ошибки. * status: Дублирует HTTP-код (удобно для логов). * detail: Подробное описание для пользователя. * instance: Ссылка на конкретный ресурс или запрос, где произошла ошибка.

Безопасность в ошибках

Главное правило безопасности при проектировании ошибок: Никогда не возвращайте Stack Trace (трассировку стека) в продакшн-среде!

~~Плохой пример:~~ "Exception in thread main: java.sql.SQLException: Access denied for user 'root'@'localhost' (using password: YES)"

Этот текст сообщает хакеру:

Вы используете Java.

Вы используете SQL-базу данных.

У вас есть пользователь root.

Пароль используется.

Это подарок для взломщика. Ошибка для клиента должна быть информативной, но безопасной: «Произошла внутренняя ошибка сервера. Номер инцидента: req-12345».

Заключение курса

Поздравляю! Вы завершили курс «Проектирование API для системных аналитиков».

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

Ваша работа как аналитика — быть мостом. Мостом между бизнесом, который хочет «чтобы работало», и разработчиками, которым нужно «четкое ТЗ». Хорошо спроектированное API — это контракт, который экономит миллионы рублей на поддержке и доработках.

Используйте полученные знания, проектируйте чисто, документируйте подробно и не забывайте про безопасность!