Здравствуйте, Sinclair, Вы писали:

S>Вам было бы легче, если бы URL второго запроса был устроен как GET /items/alice?

Было бы легче. Ресурс часто определяется именно как путь + метод. Во-первых, в инструментарии (схемы типа OpenAPI и т.п. и генерация кода на их основе, в настройке роутинга в серверных фреймворках). Во-вторых, в голове пользователя api, пытающегося воссоздать схему методом тыка и не ожидающего, что добавление query параметров меняет формат результата (кроме очевидных случаев типа ?format=xml или параметров влияющих на включение опциональных полей).

S>С т.з. REST никакой разницы между этими случаями нет.

Есть ожидания (как минимум мои) "по умолчанию" от REST. Не в том смысле, что REST должен именно так работать, а в том смысле, что когда видишь API без описания, то ожидаешь такого поведения с большей вероятностью, чем другого. Никто не обязан делать именно так, но приятнее, когда ожидания оправдываются.

Если имя уникально, то /items/alice это ресурс, от которого можно ожидать поддержки глаголов GET, PUT, DELETE и 404 при отсутствии сущности.

/items?name=alice на первый взгляд воспринимается как поиск (особенно если уникальность имени в системе вызывает сомнения). От поиска ожидаешь возврата отфильтрованной коллекции (в том числе пустой коллекции вместо 404 при отсутствии результата). Также с этой точки зрения PUT|DELETE /items?name=alice выглядит совсем уж странно.

Но пусть /items?name=alice реализован как сейчас, имя уникально. Тогда метод все равно должен возвращать 404 при отсутствии alice (или что?). Нам нужно дополнить api возможностью поиска, и в духе текущего подхода мы добавляем поддержку параметра /items?search=ali. Ищем по подстроке. Этот метод уже должен возвращать коллекцию ({ count = 3, items = [ {}, {}, {}] }), и не возвращать 404. Выглядит похоже, а поведение совсем разное, ошибиться недолго.

Здравствуйте, Sinclair, Вы писали:

S>Вам было бы легче, если бы URL второго запроса был устроен как GET /items/alice?

Было бы легче. Ресурс часто определяется именно как путь + метод. Во-первых, в инструментарии (схемы типа OpenAPI и т.п. и генерация кода на их основе, в настройке роутинга в серверных фреймворках). Во-вторых, в голове пользователя api, пытающегося воссоздать схему методом тыка и не ожидающего, что добавление query параметров меняет формат результата (кроме очевидных случаев типа ?format=xml или параметров влияющих на включение опциональных полей).

S>С т.з. REST никакой разницы между этими случаями нет.

Есть ожидания (как минимум мои) "по умолчанию" от REST. Не в том смысле, что REST должен именно так работать, а в том смысле, что когда видишь API без описания, то ожидаешь такого поведения с большей вероятностью, чем другого. Никто не обязан делать именно так, но приятнее, когда ожидания оправдываются.

Если имя уникально, то /items/alice это ресурс, от которого можно ожидать поддержки глаголов GET, PUT, DELETE и 404 при отсутствии сущности.

/items?name=alice на первый взгляд воспринимается как поиск (особенно если уникальность имени в системе вызывает сомнения). От поиска ожидаешь возврата отфильтрованной коллекции (в том числе пустой коллекции вместо 404 при отсутствии результата). Также с этой точки зрения PUT|DELETE /items?name=alice выглядит совсем уж странно.

Но пусть /items?name=alice реализован как сейчас, имя уникально. Тогда метод все равно должен возвращать 404 при отсутствии alice (или что?). Нам нужно дополнить api возможностью поиска, и в духе текущего подхода мы добавляем поддержку параметра /items?search=ali. Ищем по подстроке. Этот метод уже должен возвращать коллекцию ({ count = 3, items = [ {}, {}, {}] }), и не возвращать 404. Выглядит похоже, а поведение совсем разное, ошибиться недолго.

(И как в этом случае должен вести себя запрос /items?name=alice&search=ali ?)