Алгоритм поректирования интеграции - webkoth/style-guide-php-laravel GitHub Wiki

Данный алгоритм можно использовать при каждом проектированиии API

При этом, в разном контексте API требования могут отличаться (разработка API для блокчейн-биржы отличается от API Госуслуг).

  1. Сбор требований: начните со сбора User Story и диаграмм бизнес-процессов, которые помогут вам понять контекст, цели и ограничения интеграции.
  2. Выделение функциональных требований: проанализируйте диаграммы бизнес-процессов, User Story и определите функциональные требования, необходимые для интеграции, такие как обмен данными, синхронизация или преобразование.
  3. Выделите важные нефункциональные требования для создания качественной интеграции.
  4. Учтите необходимость масштабирования, производительности и безопасности.
  5. Система stateless или stateful (грубо - нужно ли хранить на сервере данные о запросах, или нет?).
  6. Выберите подходящий архитектурный стиль и протокол.
  7. Рассмотрите использование REST, GraphQL или gRPC, в зависимости от вашей ситуации и предпочтений.
  8. Выберите подходящий протокол для передачи данных (HTTP, HTTPS, TCP, WebSockets и т.д.).
  9. Анализ потока данных: создайте диаграммы потоков данных, которые показывают, как данные перемещаются между системами, и определите закономерности потоков данных.
  10. Определите формат обмена данными (JSON, XML, Protobuf).
  11. Разбейте ваш API на логические ресурсы и коллекции, либо эндпоинты если это RPC технология.
  12. Разработка сценариев интеграции (Use Case): на основе потоков данных определите сценарии использования, которые описывают, как системы будут взаимодействовать в конкретных сценариях, обеспечивая охват всех возможных ситуаций.
  13. Создание диаграмм деятельности UML: сопоставьте сценарии использования с диаграммами деятельности. Унифицированного языка моделирования (UML), которые обеспечивают четкую визуализацию последовательностей действий в каждом сценарии.
  14. Определите методы, которые будут использоваться (для REST) и данные (параметры) запросов и ответов.
  15. Учтите варианты пагинации, сортировки и фильтрации данных.
  16. Организуйте проверку входящих данных на валидность и целостность.
  17. Обработка ошибок и коды состояния.
  18. Предоставляйте информацию об ошибках в структурированном формате (JSON, XML и т.д.).
  19. Безопасность и авторизация.
  20. Реализуйте аутентификацию и авторизацию пользователей (OAuth, API ключи, JWT и т.д.).
  21. Защитите ваш API от распространенных угроз и атак (SQL-инъекции, XSS, CSRF и т.д.).
  22. Учтите применение политик безопасности (CORS, Content Security Policy и т.д.).
  23. Рассмотрите инструменты управления производительностью, кеширование, rate limit.
  24. Версионирование API.
  25. Планируйте изменения и обновления API, предусматривая версионирование.
  26. Используйте соглашения по именованию версий в URL или заголовках запросов.
  27. Документация.
  28. Создайте четкую и понятную документацию для вашего API, описывающую методы, параметры, коды состояния и ошибки и всю другую необходимую информацию. Также приложит примеры запросов и ответов.
  29. Задокументируйте ваш веб-сервис.
  30. Обратная связь и поддержка.
  31. Обеспечьте каналы связи для получения обратной связи от пользователей и разработчиков, использующих ваш API.
  32. На основе отзывов улучшайте ваше API.
  33. Настройте мониторинг вашего работающего API, чтобы быстро получать информацию о проблемах.