Соглашение об именах конечных точек для назначения / отмены назначения данных - PullRequest
Новая
       80

Соглашение об именах конечных точек для назначения / отмены назначения данных

2 голосов
/ 05 мая 2020

  1. Представьте, например, привязку таблицы user_tasks (user_id, task_id) с отношением m: n. Я хочу вставить новую запись. Конечная точка должна вернуть 204 Status No Content, если запись была вставлена ​​или если такая запись уже существует. Как бы вы составили такую ​​конечную точку?

    • GET users/{user_id}/tasks/{task_id}
    • POST users/{user_id}/tasks/{task_id}
    • PUT users/{user_id}/tasks/{task_id}
    • PUT user_tasks + payload: {"user_id": 1, "task_id": 2}
    • Что-то еще?

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

Теперь представьте, что в таблице есть еще один столбец: user_tasks (user_id, task_id, position). Какое здесь лучшее решение?
  • GET users/{user_id}/tasks/{task_id}/position/{position}
  • POST user_tasks + payload: {"user_id": 1, "task_id": 2, "position": 3}
  • POST users/{user_id}/tasks/{task_id} + payload: {"position": 3}
  • PUT users/{user_id}/tasks/{task_id} + payload: {"position": 3}
  • Что-то еще?

В нашем проекте есть оба случая.

1 Ответ

1 голос
/ 07 мая 2020

Похоже, что PUT подойдет вашей задаче лучше, чем GET, просто потому, что GET не должен изменять состояние на сервере.
From RF C 2616 :

Метод GET означает получение любой информации (в форме объекта), идентифицируемой Request-URI

Также оттуда:

Безопасные методы: В частности, было установлено, что методы GET и HEAD НЕ ДОЛЖНЫ иметь значение выполнения каких-либо действий, кроме извлечения. Эти методы следует считать «безопасными».

С другой стороны, для PUT:

Метод PUT запрашивает, чтобы закрытый объект был сохранен в предоставленном Request- URI. Если Request-URI относится к уже существующему ресурсу , закрытый объект ДОЛЖЕН рассматриваться как модифицированная версия того, который находится на исходном сервере.

Кажется, что он подходит хорошо, поскольку есть упоминание о возможности того, что какой-то ресурс уже существует, и мы, вероятно, не хотим создавать его снова. PUT также считается идемпотентным.

Теперь представьте, что в таблице будет еще один столбец: user_tasks (user_id, task_id, position). Какое здесь лучшее решение?

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

Лично я бы go с PUT users/{user_id}/tasks/{task_id}/assign?position=3 или с вашим подход, при котором параметры передаются через полезную нагрузку. Я думаю, что URI должен быть каким-то идентифицируемым ресурсом, тогда как user_tasks на него не похож. Это похоже на название действия, которое обычно можно увидеть в конце URI, например, посмотрите как Twitter это сделал.

...