Комментарии 4
Хорошая попытка, напомнила jsonapi спецификацию. Но сколько кода в контроллерах… еще и валидация не выделена в отдельный слой 😖 хоть и пример, но читать не приятно.
Но, мусорить так мусорить, есть еще один вариант разработки API, принцип «дополняем но не удаляем», в таких случаях сущности ответов только расширяют, но не удаляют старые данные. Со временем апишка разрастается, однако если пришла необходимость версионировать еще и мажорками REST уже что-то пошло не так, темболее на мелких проектах.
PS> в доке еще и лишний слой в виде холиварных репозиториев в ларавель с обязательной зависимостью с eloquent’ом, который и без реп поддерживает разные сторы.
Первое правило API: после релиза исходный код версии становится readonly. Представьте, а у меня один раз так и было, что Ваш API использует компьютер, замурованный в стену с одной кнопкой «перегрузить» без удаленного доступа.
Даже если деплоить один раз в день пул задач, за месяц получим тьму версий. У компании не хватит ресурсов их поддерживать, да и бессмысленно это.
Проще поступить принципом версионирования - если добавляется функционал, фиксятся баги или исправляется существующий с условием, что не нарушена обратная совместимость, то это "минор", т.е. тот же самый API.
Если что-то удаляется или ломается обратная совместимость, то это "мажор", читай другая версия.
Но всё зависит от проекта, где и как он используется. Если к нему разрешено подключаться извне любому пользователю, тогда нужно придерживаться такой тактики. Если извне нельзя и нужно для обеспечения работоспособности условно внутреннего ресурса, тогда допустимо работать в рамках одного API, меняя его в любую сторону.
Идеальный вариант версионирования достигается путём деплоя "в разные папки", грубо говоря.
На вход в приложения летят урлы, например, https://example.com/v1/foo и https://example.com/v2/foo. Сервис приёма (nginx или какая его замена) видит префикс и, в зависимости от его значения, переадресует запрос в тот или иной контейнер в случае контейнеризации либо в папку, в случае "нативного" деплоя.
Само же приложение всегда содержит лишь одну версию API с изменениями, не ломающими её функциональность. И единственная группа роутов имеет префикс v1, v2 и т.д.
Деплоим версию и всё. При возникновении критических ошибок конкретной версии, правим её и деплоим вновь.
При разработке новых критических изменений, ломающих обратную совместимость, создаём новую ветку в git с названием vN+1 (например, v3), реализуем задачу и деплоим в новую версию v3, не забыв добавить маппинг в nginx на неё.
Таким образом, получаем несколько плюсов:
Одно и то же конечное приложение может работать с разными версиями API;
Нет необходимости в одном приложении поддерживать множество параллельных версий, создавая дубликаты кода, что явно будет случаться;
Объём путаницы для разработчиков при работе с версиями сводится к нулю;
Отчётливо видно где какая версия работает.
Минусы:
При деплое новой версии необходимо внести изменения в nginx;
Добавить конфиг в supervisor и настроить крон, если они используются.
Версионирование API в Laravel-приложениях