REST API Когда использовать параметры запроса или параметры запроса?

Question

У меня есть база данных с таблицей, которая содержит workout-plans. Пример данных здесь:

{
  id: 1,
  level: 'beginner'
  week_index: 1
},
{
  id: 2,
  level: 'beginner'
  week_index: 2
},
{
  id: 3,
  level: 'advanced'
  week_index: 1
}

Как лучше всего получить конкретный предмет, используя week_index и level. Это мои текущие идеи, но я не знаю лучших практик для REST API.

/workout-plans?level=beginner&week=1
/workout-plans/beginner/1
/workout-plans/beginner?week=1

Answer 1

RESTful способ получить определенный элемент - создать форму .Вы знаете, как форма в Интернете.В этой «поисковой форме» клиент вводит неделю и уровень и получает результат или перенаправляет на список применимых тренировок.

Точный URI страницы результатов не имеет значения, хотя ваше первое решениес параметрами пути совместим с простыми формами HTML, так что это будет работать из коробки с формой HTML GET, что хорошо.

В общем, всегда думайте о том, какие HTML-страницы вы бы создали для людей, обычно этоте, которые вы должны создать и для клиентов REST.

Если вы просто не хотите использовать простой JSON поверх HTTP, в этом случае таких ограничений нет.

Answer 2

Сначала добавьте значение каждому HTTP-глаголу.

• с GET вы можете перечислить и найти один единственный результат
• используйте POST для вставки
• PUT или PATCH для обновлений
• используйте DELETE , чтобы избавиться от данных под определенным ключом.

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

Относительно просто построить клиент для отдыха, чтобы полагаться на такой контракт.

Также приветствуются специальные параметры запроса, такие как page и pageSize с правильными значениями по умолчанию.

Поскольку вы разрабатываете API, попробуйте вернуть значимые коды состояния и сообщения.

Эта статья содержит более подробную информацию, а с другой точки зрения, см. Эту аргументированную статью , выберите HATEOAS.

Answer 3

/workout-plans/ - это путь к списку планов тренировок.Таким образом, он всегда возвращает список, даже если есть только 1 результат.

Итак, /workout-plans/?level=beginner&week=1 дает 1 результат, но в виде списка.

Если это требуемый способ обращения к одному изих (по уровню и неделе, а не по идентификатору), тогда URL для получения одного из них будет выглядеть примерно так:

/workout-plans/1/beginner/
/workout-plans/beginner/1/
/workout-plans/beginner-1/

Или что-то в этом роде.

Я предпочитаю последний,поскольку он не предполагает наличие уровня между полным списком и подробным путем;если вы выбираете первое, что делать, если кто-то спросит /workout-plans/1/.

Answer 4

Решение 1: Я рекомендую это:

Я думаю, вы должны использовать /workout-plans?level=beginner&week=1.Потому что, таким образом, ясно, что вы запрашиваете данные у workout-plans контроллера.

---

Решение 2, другой способ:

Или вы можете использовать: /workout-plans/level/beginner/week/1

Например: в Rails конфигурация маршрута может быть такой:
/workout-plans/level/:level/week/:week

---

Надеюсь, это поможет.