Дизайн управления версиями API Laravel RESTful
Я новичок в Laravel (4 и 5), и в последнее время я работаю над API RESTful. Чтобы разрешить несколько версий API, я использую URL-адрес для определения версии.
Я читал, следуйте этому сообщению, и, похоже, большинство людей придерживаются этого подхода: Как организовать различные версионные контроллеры REST API в Laravel 4?
Структура папок:
/app
/controllers
/Api
/v1
/UserController.php
/v2
/UserController.php
И в UserController.php файлы, для которых я задаю пространство имен соответственно:
namespace Api\v1;
Или
namespace Api\v2;
И в маршрутах:
Route::group(['prefix' => 'api/v1'], function () {
Route::get('user', 'Api\v1\UserController@index');
Route::get('user/{id}', 'Api\v1\UserController@show');
});
Route::group(['prefix' => 'api/v2'], function () {
Route::get('user', 'Api\v2\UserController@index');
Route::get('user/{id}', 'Api\v2\UserController@show');
});
URL-адрес будет простым http://..../api/v1 для версии 1 и http://..../api/v2 для версии. Это прямолинейно.
Мои вопросы таковы: Что делать, если я создаю небольшое обновление api, скажем, версии 1.1, как мне организовать структуру папок? Моя мысль была такой, и все должно быть в порядке, так как точка - допустимое имя папок?
/app
/controllers
/Api
/v1
/UserController.php
/v1.1
/UserController.php
/v1.2
/UserController.php
/v2
/UserController.php
Кроме того, как я должен написать пространство имен? Это не такое пространство имен, как это
namespace Api\v1.1;
Существует ли соглашение об именовании, на которое я могу ссылаться при использовании "точки"?
Примечание: Я не хочу называть его версией v2, потому что это не серьезное обновление.
2 answers
IMO, незначительные обновления не должны публиковать критические изменения в API. Поэтому я предлагаю придерживаться API-интерфейсов с целочисленными версиями. Усовершенствования не являются проблемой, но существующие конечные точки должны вести себя как обычно.
Таким образом, ваши версии API будут синхронизированы с префиксами маршрутов и пространствами имен, а также с тестами.
ПРИМЕР
- Вы начинаете с версии 1.0
- Вы вносите небольшое изменение (например, git-тег v1.1), которое не приводит к критическим изменениям в ваш api. Нужно ли разработчикам делать что-то еще в своем коде? Нет, это не так. Таким образом, вы можете безопасно оставить префикс URI в
V1, чтобы разработчикам, вызывающим ваш api, не нужно было изменять весь свой код, вызывающий ваш API (и, следовательно, автоматически извлекать выгоду из новой дополнительной версии). Возможно, вы просто исправили ошибку, из-за которой их код ведет себя так, как ожидалось, или вы опубликовали новую функцию, которая сама по себе не нарушает существующие вызовы функций. - Ваше приложение растет, и вы публикуете новую переработанную версию своего API, которая содержит критические изменения. В этом случае вы публикуете новый префикс API-URI- (
V2).
Имейте в виду, что вы, конечно, можете отслеживать второстепенные версии внутри (например, в SCM), но разработчикам не нужно изменять все свои вызовы API только для того, чтобы извлечь выгоду из этого небольшого исправления, которое вы опубликовали. В любом случае, конечно, хорошо, если вы уведомите своих клиентов о новых второстепенных версиях и исправлениях ошибок или улучшения, которые они предлагают (блог, информационный бюллетень,..)
Позвольте мне добавить, что я не знаю ни о каких API-интерфейсах RESTful с незначительными префиксами API-URL, поэтому я думаю, что это довольно распространенная практика.
Вы не можете использовать точки, вместо этого используйте подчеркивания.
Но...
Хорошо разработанный api должен иметь BC между второстепенными версиями, поэтому вам не нужно создавать новую версию для незначительного обновления, вместо этого вам нужно написать совместимый код.