Переменная пути или параметр запроса?

Question

Когда мы разрабатываем Rest apis, говорят, что используют Path Variable, когда вам нужно идентифицировать ресурс, и Request Parameters, когда вам нужно выполнить такие операции, как сортировка, фильтрация, поиск, разбиение на страницы.Давайте возьмем сценарий Employee:

Сотрудник имеет три поля, такие как name, companyName, socialSecurityNo.

Теперь я хочу сотрудника с socialSecurityNo = ABC.

Кажется, что хорошо иметь конечную точку с переменной пути, например /employees/{socialSecurtityNo}, поскольку мы идентифицируем ресурс.

Также кажется интуитивно понятным, что мы фильтруем на основе socialSecurityNo и имеемконечная точка, такая как /employees?socialSecurityNo=ABC

Что будет правильным, когда я запутался и думаю, что оба варианта применимы.

Answer 1

Хороший вопрос.

/employees?socialSecurityNo=ABC

фильтрует всех сотрудников по socialSecurityNo.Если socialSecurityNo является уникальным для сотрудника, в этой конечной точке нет смысла, и клиент должен использовать /employees/{socialSecurtityNo}.

Нет ничего плохого в фильтрации по уникальному значению поля (socialSecurtityNo) и есликлиенту легче использовать эту версию (по любой технической причине), тогда это нормально.Нет «правильного» пути.Основная причина, по которой существуют API-интерфейсы, заключается в том, чтобы клиент мог выполнять ценную работу.Работайте с клиентом, чтобы это произошло, но помните о лучших практиках и знайте, когда решение не самое лучшее, но самое практичное в данной ситуации.

Я бы ожидал увидеть:

/employees?surname=Smith

, поскольку он фильтрует неуникальное значение поля и должен возвращать коллекцию Employee объектов.

«Правильный» способ сделать так, чтобы результаты были согласованными.Если у вас есть оба способа найти сотрудника, убедитесь, что возвращаемый результат одинаков в каждом случае.