Тема: АПІ версіалізація

Доброго дня, шановні!

Хто може зрозуміло розповісти про версіалізацію апі?
Я про оті магічні циферки /v1 /v2 /v3 ...
Як їх строїти в роутах і т.д. цікаво все)

2

Re: АПІ версіалізація

Найпростіший спосіб - це розкидати версії по папках (в папці api знаходять папки v1, v2), наприклад звернення до /api/v2/order буде вести до  /api/v2/order/index.php

І коли зродилася третя версію, то просто додаємо її в папку api/v3.

Якщо робити це на базі якогось фреймворка, то можна це зробити на базі контролерів чи модулів.

Подякували: oleksandr.syvolap, leofun012

3

Re: АПІ версіалізація

Підскажіть ще, як краще робити, наслідувати класи які є, чи писати всі функції по-новій?

Наприклад є якийсь базовий функціонал в v1, авторизація наприклад, ну і у версії v2 додались поля при реєстрації, а все інше не змінилось. Тобто я можу наслідувати у новій версії клас з старої версії і переписати просто 1 функцію. Наскільки це практикується і наскільки це спростить, чи ускладнить життя в подальшому, в подальшій підтримкі проекту, або ж навіть читаємості коду другим програмістом?

(Пояснювати я "майстер", знаю  :D )

4 Востаннє редагувалося koala (18.02.2020 16:52:34)

Re: АПІ версіалізація

Це виключно ваш вибір. У вас був стабільний API. Ви з якоїсь причини вирішили його змінити, але залишити відкритою версію 1. З якої саме причини? Це ваше внутрішнє питання. Можливо, якби ви нам сказали причину, то можна було б щось сказати детальніше, а так - читаність коду не має стосунку до його призначення.
Загалом я б робив директорії v1, v2 і т.д. з файлами-обгортками, які лише викликають справжні функції з вашого проєкту. Так ви надалі захиститеся від можливих змін. Доки ваша система підтримує функціонал API, вони працюватимуть.

Подякували: oleksandr.syvolap1

5

Re: АПІ версіалізація

Тут я би не наслідував нічого і задумався над тим, чи потрібно таке наслідування навіть для мінорних версій. Ну хіба якийсь базовий клас, який би формував якісь магічні методи, типу авторизацію і т.д.
Тому, що може виникнути ситуація коли треба виправити першу версію, але цього не можливо зробити, бо зламається друга-третя версія, або версія перша має застарілу логіку і її можна видалити, але як, коли все зав'язано на ній.

Подякували: leofun011

6

Re: АПІ версіалізація

koala написав:

Можливо, якби ви нам сказали причину, то можна було б щось сказати детальніше

Причина така, було, як ви і говорите, стабільне апі, яке працювало. В апі була авторизація користувачів і ще багато чого зв'язаного з користувачами, але користувачі були 1-ї ролі, тобто геть взагалі без неї. Тепер потрібно у новій версії апі зробити ролі користувачів і переписати функції і в залежності від ролі видавати різні результати (v2 версію хочуть). От у мене і стало питання. У новій версії я просто буду наслідувати старі класи з вже готовим, працюючим кодом і переписувати тільки те, що мені потрібно, чи краще писати нову версію по-новій (копіюючи з старої те що працює по-старому).

7

Re: АПІ версіалізація

NaharD написав:

Тому, що може виникнути ситуація коли треба виправити першу версію, але цього не можливо зробити, бо зламається друга-третя версія

Чому ж не можна буде? Якщо у нас наприклад та ж сама авторизація. Функціонал якої буде не змінний у всіх версіях (наслідування), потім нам треба буде виправити щось, додати колонку в таблицю юзера і заповняти її при авторизації (статуст наприклад). Ми підемо у 1 версію і змінимо там авторизації функцію, додамо потрібний функціонал і він буде працювати і у всіх інших версіях що вище. Чи я не в правильну сторону розвиваю свої думки?

NaharD написав:

або версія перша має застарілу логіку і її можна видалити, але як, коли все зав'язано на ній.

Якщо вона матиме застарілу логіку, це означатиме, що всі функції у версіях вище вже переписані по-новій, тоді ж в роутах просто її коментуємо\видаляємо. Чи я знов не так щось зрозумів?

Моя логіка полягає в тому, що наступну версію наслідувати не з 1, а з попередньої. Тобто 4-а версія буде наслідуватись від 3-ї, а 3-я від 2-ї. Чи це геть  :| ?

8

Re: АПІ версіалізація

Я б не наслідував. Бачив 2 підходи.
1) Як уже говорили, розбивати по директоріях (директорія v1, v2, і т.д., там уже всередині контролери).
Як на мене, найкращий варіант, але коли хороший дизайн софту (архітектура). Класно працює, якщо все зроблено відповідно до хороших практик: тонкі контролери, все в сервісному леєрі, в контролерах просто смикаєте сервіси і все. Для нової версії просто копі-пастите контролери. Там логіки не повинно бути, старі не правите, нові розширяєте. Десь там у вас можуть ще DTO-шки лежать теж по версіях (тут уже треба дивитися), в особливо поганих випадках починаєте правити логіку старих версій для того, щоб зробити їх зворотно сумісними (добавлення нового поля в базу не повинно вам нічого поламати, а от видалення - може. Тут і може знадобитися змінити логіку заповнення DTO)
2) Якщо так, як ви говорите про перевикористання - бачив, як таке роблять різними методами в одному контролері (різні методи для різних версій). Типу спільну логіку можна в приватний метод(и) винести. Суб'єктивно не сподобалося ;)

Подякували: oleksandr.syvolap1