это - REST URI-уникальное или множественное имя ресурса при его создании




проектирование rest api (12)

Я новичок в REST, и я заметил, что в некоторых сервисах RESTful они используют разные URI ресурсов для обновления / получения / удаления и создания. Такие как

  • Создание - использование / ресурсы с помощью метода POST (наблюдайте множественное число) в некоторых местах с использованием / resource (единственное число)
  • Обновление - использование / ресурс / 123 с помощью метода PUT
  • Get - Using / resource / 123 с методом GET

Я немного смущен об этом соглашении об именах URI. Что мы должны использовать множественное или единственное для создания ресурсов? Какими должны быть критерии при принятии решения?


Единственное число

Удобные вещи могут иметь нерегулярные множественные имена. Иногда у них их нет. Но сингулярные имена всегда есть.

например CustomerAddress над CustomerAddresses

Рассмотрим этот связанный ресурс.

Это /order/12/orderdetail/12 более /order/12/orderdetail/12 и логично, чем /orders/12/orderdetails/4 .

Таблицы базы данных

Ресурс представляет собой объект, подобный таблице базы данных. Он должен иметь логическое единственное имя. Вот answer на имена таблиц.

Отображение классов

Классы всегда сингулярны. Инструменты ORM генерируют таблицы с теми же именами, что и имена классов. Поскольку все больше и больше инструментов используются, уникальные имена становятся стандартом.

Узнайте больше о дилемме разработчика API REST API


В то время как наиболее распространенной практикой является RESTful apis, где используются множественные числа, например /api/resources/123 , есть один частный случай, когда я нахожу использование особого имени более подходящим / выразительным, чем множественные имена. Это относится к отношениям один-к-одному. В частности, если целевой объект является объектом значения (в парадигме, основанной на домене).

Предположим, что каждый ресурс имеет один-к-одному accessLog который может быть смоделирован как объект значения, т. accessLog Не является объектом, а не идентификатором. Он может быть выражен как /api/resources/123/accessLog . Обычные глаголы (POST, PUT, DELETE, GET) надлежащим образом выражают намерение, а также тот факт, что отношения действительно взаимно однозначны.


Использование множественного числа для всех методов более практично, по крайней мере, в одном аспекте: если вы разрабатываете и тестируете API ресурсов с помощью Postman (или аналогичного инструмента), вам не нужно редактировать URI при переключении с GET на PUT на POST и т. Д. ,


Как насчет:

/resource/ (not /resource )

/resource/ означает, что в папке содержится что-то под названием «ресурс», это папка «resouce».

И также я считаю, что соглашение об именах таблиц базы данных одинаково, например, таблица с именем «пользователь» является «пользовательской таблицей», в ней содержится нечто «пользователь».


Мои два цента: методы, которые тратят свое время на переход от множественного числа к единственному или наоборот, являются пустой тратой циклов процессора. Я могу быть старой школой, но в свое время, как и вещи, называли то же самое. Как искать методы, касающиеся людей? Никакое регулярное выражение не будет охватывать как человека, так и людей без нежелательных побочных эффектов.

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


Оба представления полезны. Я использовал сингулярное для удобства в течение некоторого времени, перегиб может быть затруднен. Мой опыт разработки строго особых API REST, разработчикам, потребляющим конечную точку, не хватает уверенности в том, какова может быть форма результата. Теперь я предпочитаю использовать термин, который лучше всего описывает форму ответа.

Если все ваши ресурсы находятся на верхнем уровне, то вы можете уйти с сингулярными представлениями. Избежать перегиба - большая победа.

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

Мое соглашение состоит в том, что каждый уровень глубины в URI описывает взаимодействие с родительским ресурсом, а полный URI должен неявно описывать, что происходит.

Предположим, что мы имеем следующую модель.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Если мне нужно предоставить ресурс, который позволяет клиенту получить менеджера конкретного друга определенного пользователя, он может выглядеть примерно так:

GET /users/{id}/friends/{friendId}/manager

Ниже приводятся еще несколько примеров:

  • GET /users - список пользовательских ресурсов в глобальной коллекции пользователей
  • POST /users - создание нового пользователя в глобальной коллекции пользователей
  • GET /users/{id} - получение определенного пользователя из глобальной коллекции пользователей
  • GET /users/{id}/manager - получить менеджера конкретного пользователя
  • GET /users/{id}/friends - получить список друзей пользователя
  • GET /users/{id}/friends/{friendId} - получить определенного друга пользователя
  • LINK /users/{id}/friends - добавить к этому пользователю ассоциацию LINK /users/{id}/friends
  • UNLINK /users/{id}/friends - удалить ассоциацию друзей от этого пользователя

Обратите внимание, как каждый уровень сопоставляется с родителем, на который можно воздействовать. Использование разных родителей для одного и того же объекта является нелогичным. Получение ресурса в GET /resource/123 не указывает на то, что создание нового ресурса должно выполняться на POST /resources


С соглашениями об именах обычно безопасно говорить «просто выбрать один и придерживаться», что имеет смысл.

Однако, после объяснения REST множеству людей, представление конечных точек как путей в файловой системе является наиболее выразительным способом его выполнения.
Он является безстоящим (файлы существуют или не существуют), иерархические, простые и знакомые - вы уже знаете, как обращаться к статическим файлам, будь то локально или через http.

И в этом контексте лингвистические правила могут только довести вас до следующего:

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

И мне это нравится.
Хотя, с другой стороны, это ваш каталог, вы можете назвать его «ресурсом или несколькими ресурсами», если это то, что вы хотите. Это не очень важно.

Важно то, что если вы поместите файл под названием «123» в каталог с именем «resourceS» (в результате получится /resourceS/123 ), вы не сможете ожидать, что он будет доступен через /resource/123 .

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

Примечание. Технически вы можете создавать «символические ссылки», так что /resources/123 также можно получить через /resource/123 , но первый должен существовать!


С точки зрения потребителя API конечные точки должны быть предсказуемыми, поэтому

В идеале...

  1. GET /resources должны возвращать список ресурсов.
  2. GET /resource должен вернуть код состояния уровня 400.
  3. GET /resources/id/{resourceId} должен возвращать коллекцию с одним ресурсом.
  4. GET /resource/id/{resourceId} должен возвращать объект ресурса.
  5. POST /resources должны пакетно создавать ресурсы.
  6. POST /resource должен создать ресурс.
  7. PUT /resource должен обновить объект ресурса.
  8. PATCH /resource должен обновлять ресурс, публикуя только измененные атрибуты.
  9. PATCH /resources должны периодически обновлять ресурсы, отправляя только измененные атрибуты.
  10. DELETE /resources должны удалить все ресурсы; просто шучу: код статуса 400
  11. DELETE /resource/id/{resourceId}

Этот подход является наиболее гибким и многофункциональным, но также наиболее трудоемким для разработки. Итак, если вы спешите (что всегда бывает с разработкой программного обеспечения), просто укажите resource конечной точки или resource множественной формы. Я предпочитаю единственную форму, потому что она дает вам возможность интроспективно оценивать и оценивать программно, поскольку не все множественные формы заканчиваются на 's'.

Сказав все это, по какой-либо причине наиболее часто используемый разработчик практики выбирает использовать множественную форму. Это, в конечном счете, маршрут, который я выбрал, и если вы посмотрите на популярные apis, такие как github и twitter , это то, что они делают.

Некоторые критерии для принятия решения могут быть следующими:

  1. Каковы мои временные ограничения?
  2. Какие операции я разрешу своим потребителям?
  3. Как выглядит запрос и результат?
  4. Я хочу, чтобы иметь возможность использовать отражение и анализировать URI в моем коде?

Так что это зависит от вас. Просто, что бы вы ни были последовательны.


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

Например, учитывая следующий URL:

/ Клиент / 1

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

Другой пример:

/ Оборудование / 1

В этом случае оборудование не является правильной формой множественного числа. Поэтому, рассматривая его как сборку оборудования и удаление коллекции для простоты, это согласуется с ситуацией с клиентом.


Я предпочитаю использовать как множественное число ( /resources ), так и единственное ( /resource/{id} ), потому что я думаю, что он более четко отделяет логику между работой над сбором ресурсов и работой на одном ресурсе.

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

GET /resources?Id=123

В этом случае, когда мы используем множественную версию, сервер, скорее всего, игнорирует параметр Id и возвращает список всех ресурсов. Если пользователь не будет осторожен, он подумает, что вызов был успешным и использует первый ресурс в списке.

С другой стороны, при использовании сингулярной формы:

GET /resource?Id=123

сервер скорее всего вернет ошибку, потому что Id не указан правильно, и пользователь должен будет понять, что что-то не так.


Я удивлен, увидев, что так много людей будут прыгать на множественном призрачном существительном. При внедрении единственного числа в множественные преобразования вы занимаетесь нерегулярными множественными существительными? Вам нравится боль?

См. http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Существует много типов нерегулярного множественного числа, но они наиболее распространены:

Тип существительного Формирование множественного числа Пример

Заканчивается на -fe Изменить f на v затем Добавить-ножи ножи жизни жизни жены жен Окончание с -f Изменить f на v затем Добавить -пополовину половинки волк-волки буханки хлеба Конец с -o Добавить-картофельный картофель томатные помидоры вулканы вулканы концы с -us Change -us to -i cactus ядра ядра ядра ядра кактуса заканчивается с -is Change -is--e-анализ анализирует кризисные кризисы тезисы тезисов заканчиваются на -on Change-to -a феномен явлений критерий критерия ВСЕ ВИДЫ Изменение гласного или Изменить слово или Добавить другого человека по окончанию Человек ноги ноги дети дети человек люди зубы зубы мышь мыши неизменные Сингулярное и множественное число - это одни и те же овечьи рыбы оленя (иногда)


множественное число

  • Простой - все URL-адреса начинаются с того же префикса
  • Логический - orders/ получает индексный список заказов.
  • Стандарт - наиболее распространенный стандарт, за которым следует подавляющее большинство публичных и частных API.

Например:

GET /resources - возвращает список ресурсов

POST /resources - создает один или несколько элементов ресурса

PUT /resources - обновляет один или несколько элементов ресурса

PATCH /resources - частично обновляет один или несколько элементов ресурса

DELETE /resources - удаляет все элементы ресурсов

И для отдельных ресурсов:

GET /resources/:id - возвращает определенный элемент ресурса на основе :id параметра

POST /resources/:id - создает один элемент ресурса с указанным идентификатором (требует проверки)

PUT /resources/:id - обновляет определенный элемент ресурса

PATCH /resources/:id - частично обновляет конкретный элемент ресурса

DELETE /resources/:id - удаляет определенный элемент ресурса

Для сторонников единства, подумайте об этом так: не могли бы вы спросить кого-нибудь о order и ожидать чего-то, или список вещей? Итак, почему вы ожидаете, что служба вернет список вещей при вводе /order ?





uri