Создание, публикация и управление версиями ресурса с помощью REST

Question

Я занимаюсь разработкой веб-сервиса, в котором все промежуточные изменения должны быть версионированы (Черновики), и пользователи могут публиковать (Жить свои изменения). Чтобы пользователи продолжали ссылаться на более старые версии (например, по причинам совместимости), пользователи также должны иметь возможность получать более старые состояния.

Вот как выглядит мой текущий дизайн

+------------------+-------------------------------------------+--------------------------------------------------------------+-------------------------------------------------+
|      action      |                  request                  |                            response                          |                state of resource                |
+------------------+-------------------------------------------+--------------------------------------------------------------+-------------------------------------------------+
| create a post    | post                                      | status=201 id=123 and version=v1                             | resource created with version v1                |
| update the post  | put with id=123 and version=v1            | status=200 id=123 and version=v2                             | new version of resource created with version=v2 |
| update the post  | put with id=123 and version=v2            | status=200 id=123 and version=v3                             | new version of resource created with version=v3 |
| update the post  | put with id=123 version=v1                | status=409 and body indicating user is editing stale version |                                                 |
| publish the post | put with id=123 version=v2 action=publish | status=200 id=123 version=p1 (p indicating published)        | new version created with version=p1             |
| get all versions | get list with id=123 status=all           | status=200 and v1,v2,p1 in the body                          | no change                                       |
+------------------+-------------------------------------------+--------------------------------------------------------------+-------------------------------------------------+

Соответствует ли вышесказанное архитектуре покоя? Я беспокоюсь о следующих проблемах:

1. Здесь Put не идемпотентен, так как он создает новую версию каждый раз, когда мы делаем это.

2. Пользователь должен знать о действии = Опубликовать для публикации статьи. нормально ли иметь эту информацию в IMO на стороне клиента в теле ответа put / get / post, мы должны сообщить всем поддерживаемым операциям что-то вроде этого

{
  "body": {...}
  "actions": [
    {
      "type": "publish",
      "uri": "/order/123/publish"
    },
    {
      "type": "save",
      "uri": "/order/123/save"
    },
    {
      "type": "archive",
      "uri": "/order/123/archive"
    }
  ]
}

3. Есть ли что-то, чего мне не хватает

Не слишком ли педантичен к деталям?

Answer 1

Учитывая, что вы используете подход в стиле hateoas, я бы порекомендовал следующее:

1. Имейте один URI, который всегда представляет последнюю версию.Например, /order/123.
2. Создание ссылок с типами отношений из RFC5829 на другие версии.Примеры: version-history, latest-version, predecessor-version, successor-version.Используйте только те отношения ссылок, которые вам нужны.Разные версии - это просто разные ресурсы.
3. Вместо использования action вы можете пометить ресурс как public или draft, используя свойство (например, isPublic).Если установлено значение true, эта версия становится публичной версией.Последняя «версия» с этим статусом станет той, которая действительно «жива».

Решение проблемы идемпотентности PUT

Учитывая, что PUT создаетновая «версия» каждый раз, когда вы запускаете ее, она все еще идемпотентна?Я думаю, что это становится немного сложнее, чтобы ответить.Является ли эффект 2-х запросов PUT таким же, как просто выполнение 1?

Хорошо, если вы рассмотрите журналы HTTP-доступа, 2 идентичных запроса PUT также вызовут 2 записи.Я действительно не знаю, как это согласовать, но я думаю:

1. 2 идентичных запроса PUT по-прежнему создает предполагаемое состояние.Обновление основного ресурса.Теперь есть дополнительный (версионный) ресурс, но, может быть, это не имеет значения?
2. Вы можете выбрать , а не создать новую версию ресурса, если он на самом деле не изменился, обходя это полностью.