RESTful API: как спроектировать URI, по строке запроса или иерархически?

Question

У меня есть «нормальное» веб-приложение, в котором я перечисляю услуги по всему миру. Существует 2 способа составления списка книг: 1) с помощью поля поиска или 2) с использованием иерархического дизайна пути.

Пример 1) Поле Seach генерирует URI, такие как: mysite.com/en/services?location=london&category=lowcost

Пример 2) Путь как: mysite.com/en/services/uk/london/lowcost

В обоих примерах указан один и тот же сервис.

Но теперь я должен написать RESTful API. Итак, мой вопрос: Какой интерфейс / способ я должен предложить своим клиентам API? Я имею в виду, если они просто запрашивают мои данные, используя строку запроса (пример 1), или они сами строят путь, это означает, что они должны знать, например, что Лондон принадлежит Великобритании :) (или Чианг-маю Таиланд) ...

Было бы неплохо предложить оба варианта? Но, если я предложу и то, и другое, это хороший дизайн RESTful API, в котором 2 ресурса (в данном случае наборы) предназначены для одного и того же ресурса?

Answer 1

Путь для иерархии, строка запроса для фильтрации.

1. Если это суперкатегория именованного объекта, он указывается в пути.
2. Если он однозначно идентифицирует именованный объект, он является последним компонентом пути.
3. Если это свойство или подобъект именованного объекта, который не уникально идентифицирует объект, он помещается в строку запроса.