Дизайн REST Api для обновления одного атрибута ресурса

Согласно спецификации проекта, над которым я работаю, требуется предоставить API, который позволяет изменить статус объекта пользователя на один из [VALID | NOT_VALID | TO_VALIDATE].

Текущий API для пользователей имеет этот путь / user /: user_id, моя идея заключалась в том, чтобы добавить новый подпуть для POST с url: / user /: user_id / status

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

  • Использование тела запроса (JSON)
  • Используя строку запроса, например / user /: user_id / status? value = VALID
  • Creating three endpoints, one for each possible status' value:
    • /user/:user_id/status/valid
    • / пользователь /: идентификатор_пользователя / статус / not_valid
    • / пользователь /: идентификатор_пользователя / статус / to_validate

Спасибо.


api rest api-design
person Fr.Usai    schedule 31.08.2016    source источник
comment
Вы можете сослаться на этот stackoverflow.com/questions/2443324/   -  person Jugal Panchal    schedule 31.08.2016

Ответы (1)


arrow_upward
2
arrow_downward

Если статус - это что-то, что не может быть запрошено, вы даже можете иметь его как часть самого объекта пользователя, например / user /: user_id, и выполнить PATCH (с полезной нагрузкой JSON) для обновления статуса. Обычно люди предпочитают вложенные пути, если подпуть можно запросить как подресурс сам по себе или обновить независимо. Итак, если кому-то нужен статус пользователя, разве он не ожидал бы, что это придет в результате GET / user /: user_id? Или он должен сделать еще один вызов GET для / user /: user_id / status? Я думаю, что путь / status не может быть хорошей идеей.

Кроме того, если вы добавите что-то вроде статуса сейчас, что произойдет, если вам понадобится обновить имя, адрес и т. Д. В будущем. Мы же не хотим продолжать добавлять новые подпути для каждого поля, верно? Кроме того, наличие подпути, подобного перечислению, в пути URL (действительный / not_valid и т. Д.), Похоже, не является правильным. Если вы включите его в полезную нагрузку JSON, он попадет в схему, и вы сможете создать его красивую версию на случай, если вы внесете новые дополнения в перечисление. Наличие его как части URL-адреса означает, что теперь клиенты также должны знать о новом пути.

С другой стороны, вы также должны подумать об удобстве использования API. Одно практическое правило, которое я обычно придерживаюсь при разработке REST API: я хочу, чтобы мои клиенты интегрировались с моим API за 2 минуты или около того, и я должен свести к минимуму количество вещей, которые ему нужно знать для успешной интеграции. Все стандарты и нормы могут оказаться вторичными по отношению к удобству использования.

person Ramkumar Venkataraman    schedule 31.08.2016