Дизайн версий Laravel RESTful API

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

Кажется, что большинство людей следуют этому подходу: организовать разные версии контроллеров REST API в Laravel 4?

Структуры папок:

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

И в UserController.php файлах я соответствующим образом устанавливаю пространство имен:

namespace Api\v1;

or

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 для версии 2. Это просто.

Мои вопросы:
Что делать, если я создаю незначительное обновление 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, потому что это не серьезное обновление.


person Sam Wong    schedule 14.05.2015    source источник


Ответы (3)


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

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

ПРИМЕР

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

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

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

person nozzleman    schedule 14.05.2015
comment
привет соплман, твой взгляд отличается от аэрягузов. Вы имеете в виду, что это должна быть v2 вместо v1.1 и не вносить никаких изменений в существующие коды v1? - person Sam Wong; 14.05.2015
comment
Спасибо за ответ! Я отредактировал ответ. Надеюсь, я немного яснее изложил свою мысль. - person nozzleman; 15.05.2015
comment
Я также рассматриваю возможность реализации версий API. Если использовать эту структуру управления версиями для v1, v2 и т. д., будут ли какие-либо проблемы при запуске композитора и создании дампа автозагрузки? - person JBMcClure; 16.10.2015
comment
Я не знаю, что вы имеете в виду. Может быть, это квалифицирует так отдельный вопрос. - person nozzleman; 16.10.2015
comment
@JBMcClure, соплямн хочет сказать, что они не могут быть серьезными изменениями для версии, например, с 1.1 по 1.2, и это можно сделать, используя if else только в этом конкретном API. - person Ashutosh; 04.10.2017

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

Но...

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

person aeryaguzov    schedule 14.05.2015
comment
Поймите свою точку зрения. Это означает, что я должен расширить или добавить новые коды в контроллер v1. - person Sam Wong; 14.05.2015

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

https://github.com/mbpcoder/laravel-api-versioning

person Mahdi Bagheri    schedule 06.07.2020