Подтвердить что ты не робот

Дизайн дизайна LARARE 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;

или

namespace Api\v2;

и в маршрутах:

Route::group(['prefix' => 'api/v1'], function () {
  Route::get('user',      'Api\v1\[email protected]');
  Route::get('user/{id}', 'Api\v1\[email protected]');
});

Route::group(['prefix' => 'api/v2'], function () {
  Route::get('user',      'Api\v2\[email protected]');
  Route::get('user/{id}', 'Api\v2\[email protected]');
});

URL будет простым http://..../api/v1 для версии 1 и http://..../api/v2 для версии. Это прямо.

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

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

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

namespace Api\v1.1;

Есть ли соглашение об именах, на которое я могу ссылаться для использования "точки"?

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

4b9b3361

Ответ 1

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

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

Пример

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

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

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

Ответ 2

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

Но...

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