Laravel RESTful API versioning design

Question

Я новичок в Laravel (4 и 5), а недавно я работаю над RESTful API. Чтобы разрешить несколько версий API, я использую URL для определения версии.

Я прочитал этот пост следовать, и это, кажется, что большинство людей после этого подхода: How to organize different versioned REST API controllers in 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 для версии. Это прямолинейно.

Мои вопросы: Что делать, если я строю незначительные обновления АФИ, скажем, v1.1, как я организую свою структуру папок? Я думал, что это так, и должно быть все равно, как точка является действительным именем папок?

/app 
    /controllers 
    /Api 
     /v1 
     /UserController.php 
     /v1.1 
     /UserController.php 
     /v1.2 
     /UserController.php 
     /v2 
     /UserController.php 

Кроме того, как я должен писать пространство имен? Это не пространство имен, как этот

namespace Api\v1.1; 

Есть ли именование я могу сослаться на использование «точки»?

Примечание: Я не хочу называть его версией v2, потому что это не серьезное обновление.

Answer 1

IMO, незначительные обновления не должны публиковать нарушения API. Поэтому мое предложение - придерживаться целочисленных версий API. У улучшений нет проблем, но существующие конечные точки должны вести себя как обычно.

Таким образом, ваши API-версии будут синхронизироваться с префиксами маршрута и пространствами имен, а также с тестами.

Пример

1. Вы начинаете с версией 1.0
2. Вы делаете небольшие изменения (например. ГИТ-теги v1.1), которая не приносит ломать изменения в API. Нужно ли разработчикам делать что-либо еще в своем коде? Нет, нет. Таким образом, вы можете безопасно оставить URI-префикс на V1, так что разработчикам, вызывающим ваш api, не нужно изменять весь их код, который вызывает ваш API (и, следовательно, автоматически извлекает выгоду из новой младшей версии). Возможно, вы просто исправили ошибку, что делает их код так же, как и ожидалось, или вы опубликовали новую функцию, которая сама по себе не нарушает существующие функции-вызовы.
3. Ваше приложение растет, и вы публикуете новую измененную версию вашего API, которая содержит взломанные изменения. В этом случае вы публикуете новый API-URI-префикс (V2).

Помните, что вы можете, конечно, отслеживать второстепенные версии внутри (например, в SCM), но разработчикам не нужно будет менять все свои API-вызовы, чтобы извлечь выгоду из этого небольшого исправления. опубликован. В любом случае, приятно, если вы сообщите своим клиентам о новых младших версиях и исправлениях или улучшениях, которые они предлагают (блог, информационный бюллетень, ..)

Позвольте мне добавить, что я не осведомлен о каких-либо RESTful API-интерфейсах с второстепенные префиксы API-URL, поэтому я думаю, что это довольно распространенная практика.

Answer 2

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

Но ...

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