Проектирование API (продолжение)

Open API. Для того, чтобы мы не оказались как в кабине самолета с ростом API, нам нужна документация. Также наверняка ни у кого нет желания закопаться в сотне листов бумаги или страниц confluence. Для решения этой проблемы и начал развиваться проект Open API.

The OpenAPI Specification как продукт вышел в 2017 году и по сути является 3-й версией Swagger.

Документацию можно писать с помощью OpenAPI 2 способами: 1. Прямо в коде. 2. Отдельно от кода.

Какие у нас есть для этого инструменты: 1. Swagger Core - генерация документации в коде с помощью нотаций и других элементов. 2. Swagger Codegen - генерация клиентов, которые мы описали в коде. 3. Swagger UI - удобное для пользователя отображение документации и возможность выполнить запросы прямо в документации. 4. Swagger Editor возможность написания документации в JSON формате или YML.

Преимущества OpenAPI: 1. Упрощенная генерация тестов. 2. Возможность выполнить запрос без дополнительных инструментов. 3. Встраиваемая аутентификация и авторизация. 4. Документация рядом и с живыми примерами.

Понимая базовую основу построения сервисов на основании модели OSI и принципов работы протокола HTTP, мы можем не только контролировать разработку сервисов, закладывая в процесс такие архитектурные паттерны, как rate limiter и retry базово и обязательно, но и корректно готовить инструкции для сопровождения и поддержки, учитывая работу всех слоев.

Также понимая зону ответственности сервиса с точки зрения модели OSI, мы точно можем заложить в процесс разработки определенные уровни тестов для конкретного слоя и проверить, как отреагирует наш сервис в одном и нескольких экземплярах.

Для более глубокого погружения в проектирование RESTful API рекомендую к прочтению https://restcookbook.com/https://roy.gbiv.com/untangled/http://restfulwebapis.org/

Альтернатива клиент-серверной архитектуре, построенная без REST — это интеграция, основанная на событиях. В этой модели каждый компонент непрерывно передает события, перехватывая соответствующие события из других компонентов. В ней нет взаимодействия один-к-одному, только передача и перехват. REST требует взаимодействия один-к-одному, поэтому архитектура, основанная на событиях, не будет удовлетворять требованиям RESTful.

В этой парадигме мы детально должны посмотреть на такие паттерны, как: * Event Sourcing Command & Query Responsibility Segregation (CQRS) Особенности CQRS и ES. Про них в небольших коротких статьях я расскажу в следующих постах.

Интересно узнать ? 👍

Мой ТГ канал - https://t.me/carbonka