REST API / URL дизайн для ресурсов с методами плюрализации / публикации

Question

Скажем, например, у меня был дизайн REST api url с "Customer" в качестве ресурса.

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

Верны ли эти примеры URI?
Или я должен делать это по-другому ..?

/ клиент / 1234
получить клиента с идентификатором 1234

/customer/email/john@smith.com
получить клиента с адресом электронной почты

[POST]
/ клиент /
создает нового клиента

/ клиентов /
список всех клиентов (уведомление о плюрализации)

Answer 1

По моему опыту, API-интерфейсы RESTful используют один путь к ресурсу во множественном числе.Идея состоит в том, что у вас есть customers, и когда вы хотите взаимодействовать с клиентом, вы взаимодействуете с ресурсом customers в целом.

GET /customers, чтобы получить список клиентов.

POST /customers для создания нового клиента.

GET /customers/:id для получения конкретного клиента с уникальным идентификатором.(Обычно это не атрибут клиента, такой как email)

GET /customers?email=bob@example.com, чтобы получить клиентов с определенным значением атрибута.

У Apigee есть сообщение в блоге , которое охватываетмножественное число, которое вы можете прочитать.

Answer 2

Если бы я разрабатывал этот API, я бы начал с универсального типа гипермедиа, такого как HAL, и разработал корневое представление, которое предоставляет мне доступ к различным сценариям, которые вы описываете, используя ссылки и шаблоны URI.

например

GET /api
=>
<resource>
   <link rel="urn:mycompany:customer" href=".../{id}"/>
   <link rel="urn:mycompany:customers" href="..."/>
   <link rel="urn:mycompany:customersearch" href="...{?email}"/>
</resource>

Я не заполнил фактические URL, потому что с точки зрения потребителя API действительно не имеет значения, как эти URL структурированы.Делайте все, что проще в вашей серверной среде.Не беспокойтесь, если вы ошиблись, вы можете изменить это позже, и ваши клиенты не сломаются, потому что они должны обнаружить URL из корневого представления.

Принято считать, что размещение клиента в группе клиентов создаст нового клиента, поэтому вы можете просто потребовать, чтобы ваши потребители использовали эту ссылку.Или, если вы хотите быть более явным, вы можете определить новое отношение ссылки, которое предоставляет URL для создания клиентов.

Answer 3

Почему бы не быть надежным и включить как / customer, так и / customer?

GET / customer / 1234 или / Customers / 1234 получает один и тот же ресурс.on / customer или / Customers дает список всех клиентов.

POST для / customer или / Customers создает нового клиента.

Answer 4

Вот как я бы это сделал:

/ customer / 1234

customer/john@smith.com или (если электронная почтане гарантируется, что он будет уникальным)

[GET] / клиенты /

Приветствия,

Ferenc