Почему бы не рассмотреть модели в версии REST API? - PullRequest
Новая
       20

Почему бы не рассмотреть модели в версии REST API?

0 голосов
/ 25 мая 2019

Был ответ на аналогичный вопрос , но он слишком специфичен для примера и не отвечает вообще.

Может ли кто-нибудь подсказать, как справиться с приведенным ниже сценарием, если модели не имеют версий? 

PUT /v1/users
username (string)
email (string) (required)
password (string) (required)

POST /v2/users
username (string) (required)
email (string) required
password (string) (required)

Предполагая, что имя модели UserModel , в версии v1 имя пользователя необязательно, но в версии V2 это необходимо.

Если мы используем валидатор схемы, такой как ajv, он завершается ошибкой даже для запросов API v1, поскольку в последней спецификации / модели указывается, что поле username обязательное.

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

1 Ответ

4 голосов
/ 25 мая 2019

Возможно, вы путаете модели, представляющие домен вашего приложения, с моделями, представляющими данные , обрабатываемые вашим API .

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

Сказав, что, хотя ваш уровень обслуживания работает по моделям домена / персистентности, ваши контроллеры API должны работать по другому набору моделей.

По мере того, как модели вашего домена / постоянства развиваются для поддержки новых бизнес-требований, например, вы можете захотеть создать новые версии моделей API для поддержки этих изменений. Вы также можете отказаться от старых версий вашего API по мере выпуска новых версий. Когда ваши клиенты обновят свой код, вы можете отказаться от поддержки старых версий.

* +1025 * Пример

Для примера представим, что вы создаете приложение для управления задачами. А вот как вы представляете задачу в своем домене: 

+----------------------+
|         Task         |
+----------------------+
| - id: Long           |
| - title: String      |
| - completed: Boolean |
+----------------------+

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

Чтобы создать задачу в вашем API, клиенты должны POST представить JSON-представление задачи с title и логическим значением, указывающим, является ли задача completed или нет. Они не должны предоставлять значение для id, так как оно будет сгенерировано сервером. Хорошие вещи.

Существуют разные способы управления версиями вашего API, включая URL-адреса и управление версиями медиа-типа Это большая тема, и в этом ответе я не буду рассказывать о плюсах и минусах каждого подхода. Однако в качестве примера я буду использовать управление версиями медиа-типа: 

POST /tasks HTTP/1.1
Host: example.org
Content-Type: application/vnd.foo.v1+json

{
  "title": "Send report to manager",
  "completed": false
}

Спустя долгое время после выпуска приложения в производство вы понимаете, что использование логического значения для представления состояния задачи не является хорошим. А использование перечисления с некоторыми значениями, такими как NOT_STARTED, STARTED и COMPLETED, будет намного лучше соответствовать вашим бизнес-требованиям, чем логическое значение.

Это потребует изменения модели вашего домена и базы данных. Вот как будет выглядеть ваш домен: 

+----------------------+
|         Task         |
+----------------------+
| - id: Long           |
| - title: String      |
| - status: String     |
+----------------------+

Итак, вы выпускаете новую версию вашего API. Представление задачи теперь имеет свойство status, а не completed: 

POST /tasks HTTP/1.1
Host: example.org
Content-Type: application/vnd.foo.v2+json

{
  "title": "Send report to manager",
  "status": "NOT_STARTED"
}

Это намного круче. Но не забывайте, что ваше приложение уже работает, и вы не хотите ломать клиентов, которые используют ваш старый API.

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

При отображении старого представления задачи в модель предметной области вы должны учитывать следующее:

  • Если completed равно true, то задача status будет COMPLETED
  • Если completed равно false, то задача status будет NOT_STARTED
...