Версионность API в Symfony?

Question

[Игорь]

Коллеги, добрый день!

Разрабатываем небольшой проект.
Пишем API.

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

Предполагаем несколько вариантов.

1. Номер версии передавать в качестве параметра при выполнении запроса, так как это делает vk.com
https://domain.com/users.get?v=0.1
Внутри реализовать некий механизм, предполагаем что это будет некий треш с новыми функциями.

2. Так как проект будет полностью "докеризирован" то можно было бы форкать проект и изменять конфигурацию.
При этом, не придётся плодить роуты, методы, ...
И мне кажется это параллелит с VCS. Если речь идёт о кардинальном изменении логики приложения.

Какие есть ещё способы?

Symfony 5

FOSRestBundle не предлагать, в Symfony 5 не работает.

Comments

[Игорь]

Максим Федоров,

Да, это рассматриваем, тоже.
Наверное это самый первый вариант, который пришёл в голову.
Нам он показался простым, но надёжным.

В аннотации имени класса можно указать прификс.

Спасибо.

Answer 1

[Максим Федоров]

Предлагаю работать как все норм ребята

• Создать папку контроллеров /V2/ (ну или/и добавить V2 в название контроллера для удобного поиска в IDE)
  
• Настроить префикс для всех этих контроллеров как /v2 одной строкой в роутах (ну или если в аннотациях задаете -- в них указать префикс)
  

Дока: Route Groups and Prefixes¶

И не мудохаться с квери-параметром
Такие возможности у вас под рукой, какой параметр вы там надумали как в нулевых?!

Ну это конечно, если вы в контроллерах говна не нагородили, если сделано чисто -- то контроллер как расходка,
контроллер + парочка ДТО под нужную версию

UPD от tommy-vercetti:

Не стоит юзать JMS сериалайзер или Symfony Serializer с аннотациями для сущностей. Для респонсов можно использовать обычные DTO-шки либо fractal.

API доку удобно писать с помощью https://github.com/bukalapak/snowboard

Comments

[Игорь]

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

Что тогда?

Эта модель перестанет отвечать требованиям, даже если мы нормальные ребята.

[Максим Федоров]

Игорь, не понял

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

Зависит от политики обратной совместимости.
Совместимый код придется писать определенным образом, добавляя новую фичу, нужно соблюсти совместимость со старой (или не совмещать)

[Максим Федоров]

Игорь,
пример

Есть некий функционал товаров с одной картинкой. у товара
Теперь в 2й версии вы добавили новый функционал "все картинки" товара

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

Если у вас начинает пересекаться/конфликтовать функционал -- тут разные эвристки и классы помогут вам, все не так сложно и довольно комфортно

[Игорь]

tommy-vercetti, Отличное дополнение.

[Игорь]

При последующих мажорных версияъ, например больше не планируется использование сущности User, а предположим что вместо User это будет Account

User и Account кардинально различаться.

Как мы понимаем это таблицы в базе данных.

users
accounts

Если требуется исключить сущность в следующем релизе.
Тут вполне резонный вопрос.
Зачем нам нужна таблица users в версии v2?

[Максим Федоров]

Игорь,

Зачем нам нужна таблица users в версии v2?

Хочу отметить, что "в версии 2" -- это в том же приложении, где есть и v1
В версии v2 значит эта таблица не будет использоваться, а если замена юзерам в accounts, то для v1 нужно сделать транфсормацию, чтобы туда в ДТО прилетали данные из accounts

[Игорь]

Максим Федоров, Это понятное дело.

Но что если в версии 2 нам это ненужно, а в 1 версию ломать не следует.

[Максим Федоров]

Игорь, что не нужно?

[Игорь]

Максим Федоров, Я имею в виду разницу структуру базы данных.

[Игорь]

То есть, самый простой вариант, версионирования
Это

bin/console make:controller Api\V1\Product
bin/console make:controller Api\V2\Product

[Игорь]

PS C:\Projects\rit> docker-compose -f dc.dev.yml exec app php  bin/api debug:router
 -------------------------- -------- -------- ------ -----------------
  Name                       Method   Scheme   Host   Path
 -------------------------- -------- -------- ------ -----------------
  app_api_v1_product_index   ANY      ANY      ANY    /v1/product.get
  app_api_v2_product_index   ANY      ANY      ANY    /v2/product.get
 -------------------------- -------- -------- ------ -----------------

[Игорь]

[Максим Федоров]

Игорь, да, вполне...
данные для контроллеров будут прилетать через ДТО-шки и трансформеры, а логику их создания и источник данных уже программируйте так, как нужно

[Максим Федоров]

Игорь, только я бы в название добавил бы V2:
ProductControllerV2.php

[Игорь]

Максим Федоров, как вы считаете, что если эту самую версионность обеспечить системой GIT, для того чтобы можно было собирать нужные контейнеры в докере.

Приведу пример.

https://example.com/v1/users.get
https://example.com/v2/users.get

Проект полностью докерезирован.
В теории, можно было бы конфигурировать уже готовые контейнеры.

Контейнер (Версия 1) - https://example.com/v1/users.get
Контейнер (Версия 2) - https://example.com/v2/users.get

В теории это работает.

Максим Федоров, Я почему об этом думаю, не хотело бы загрязнять код, не актуальными роутерами.

Прилагаю схему

Answer 2

[grabbee]

Версионирование кем-то считается устаревшей практикой.
Рекомендуют использовать "устаревание"(deprecated)
https://api-platform.com/docs/core/deprecations/#d...

Comments

[Игорь]

Да, конечно.
Можно считать это хорошей практикой.