Архитектурный стиль взаимодействия компонентов распределенной системы к компьютерной сети.
6 разграничений:
- Разграничение на клиент и сервер (Client-Server)
- Сервер не хранит состояние запроса (Stateless)
- Кэширование запросов (Cache)
- Единый формат взаимодействия (Uniform Interface)
- Слои для управления нагрузкой, балансировкой и масштабированием (Layered System)
- Клиент может расширять функциональность за счет загрузки кода с сервера (аплетов или сценариев) (Code-On-Demand) (optional)
RESTful Service — сервис полностью отвечающий архитектурному стилю REST
API DLs — Application Programming Language Description Language — Язык для представления описания интерфесов, понятный и человеку и машинем
Основные языки описания:
- Swagger
- OpenAPI Specification (OAS)
- WSDL (Web Services Description Language) — это язык описания веб-сервисов и доступа к ним, основанный на языке XML.
- API Blueprint
- RAML (RESTful API Modeling Language)
- RSDL (RESTful Service Description Language)
- WADL (Web Application Description Language) — машинно-читаемое XML-описание для web-приложений HTTP (как правило, веб-сервисы REST). Аналог WSDL для SOAP.
- GCE (Google Cloud Endpoiints)
OpenAPI Specification (OAS) — спецификация интерфейса, не зависит от языка программирования
Swagger
Спецификация+Программа Swagger до версии 3.0 была разработана в 2011 году компанией SmartBear для компании Wordnik (онлайн-словарь английского языка) под лицензией Apache 2.0. В 2015 году переименована в OpenAPI Specification и выложена на GitHub.
Начиная с версии Swagger 3.0 спецификация стала отдельно — OpenApi Spec и отдельно программа Swagger tools
Подходы в разработке:
API Design First
Сначала проектируется интерфейс, а затем разработчики разрабатывают код в соответствии
Code First
Подходит для маленьких интерфейсов
Code First
Code First Аннотации для Java / Kotlin
API Design First
OpenAPI спецификация — описывается в формате yml или JSON
Основные блоки:
Практические советы
- Использовать только JSON формат для взаимодействия компонентов (микросервисов)
- Для описания Endpoints использовать имена существительные
- Для коллекций использовать множественное число
- Использовать хлебные крошки — если одна сущность является содержит другую, то путь до эндпоинта вложенной сущности должен быть с указанием сущности в которую она вложена. Например: Инструменты/Электро Инструменты/Шуруповерты/Makita-123
- Использовать адекватное ошибок и типы ошибок
- Использовать постраничный вывод, фильтрац
- Использовать версионирование API
Swagger Framework
- Swagger Editor
- Swagger UI
- Swagger Codegen
Swagger Codegen
Позволяет генерировать из спецификации набор клиентов на различных языках программирования
Swagger Editor
Позволяет создавать и редактировать схему
Swagger UI
Позволяет посмотреть на красивое описание по готовой спецификации и сгенерировать запросы по данной спецификации
Postman
Может сгенерировать коллекцию запросов по OpenApi спецификации
Insomnia
Отображает OpenApi спецификацию, как Swagger Editor
OpenApi Tools
ПО для работы с OpenApi спецификацией
Например Mock Servers — позволяют замокать другие микросервисы для проверки интеграционной разработки локально. Это фековые сервисы — которые дают ваш определенный ответ на ваш определенный запрос.
Проект Pet Store
Проект Pet Store для демонстрации Swagger UI и написания спецификации OpenApi
OpenApi спецификация проекта Pet Store
WireMock Cloud
API First (Contract First) и API Design
API Design — проектируем дизайн, отдаем разработчикам
API First — самое ценное это интерфейс — всё ради того чтобы он был понятен
Источник
В дополнение:
