Как создать REST URL без глаголов?

Я изо всех сил пытаюсь определить, как создать спокойные URL-адреса. Я полностью за спокойный подход использования URL с существительными, а не глаголами, не понимаю, как это сделать.

Мы создаем сервис по внедрению финансового калькулятора. Калькулятор принимает несколько параметров, которые мы будем загружать через файл CSV. Варианты использования будут включать:

1. Загрузить новые параметры
2. Получить последние параметры
3. Получить параметры для определенной бизнес-даты
4. Сделайте набор параметров активным
5. Проверить набор параметров

Я полагаю, что спокойный подход будет иметь следующие типы URL:

/parameters
/parameters/12-23-2009

Вы можете достичь первых трех вариантов использования с:

1. POST, где вы включаете файл параметров в запрос поста
2. ПОЛУЧИТЬ первый URL
3. ПОЛУЧИТЬ второй URL

Но как вы делаете 4-й и 5-й вариант использования без глагола? Разве вам не нужны такие URL, как:

/parameters/ID/activate
/parameters/ID/validate

??

Возможно что-то вроде:

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }

Общие принципы для хорошего дизайна URI:

• Не используйте параметры запроса для изменения состояния
• Не используйте смешанные пути, если вы можете помочь; строчная лучше
• Не используйте специфичные для реализации расширения в ваших URI (.php, .py, .pl и т. Д.)
• Не впадайте в RPC с вашими URI
• Как ограничить URI пространства как можно больше
• Do Сегменты Keep путь короткие
• Do предпочитают либо /resourceили /resource/; создать 301 перенаправления из того, который вы не используете
• Есть ли параметры использования запроса для суб-выбора ресурса; т.е. нумерация страниц, поисковые запросы
• Do ход вещи из URI , который должен быть в теле HTTP заголовка или

(Примечание: я не сказал «RESTful URI design»; URI по существу непрозрачны в REST.)

Общие принципы выбора метода HTTP:

• Никогда не используйте GET для изменения состояния; это отличный способ, чтобы робот Google испортил ваш день
• Не используйте PUT, если вы не обновляете весь ресурс
• Не используйте PUT, если вы также не можете законно сделать GET на тот же URI
• Не используйте POST для извлечения информации, которая является долговременной или может быть целесообразной для кэширования
• Не выполняйте операцию, которая не идемпотентна с PUT
• Есть ли использовать GET для как можно больше
• Есть ли использовать POST в предпочтении к PUT , если сомневаетесь
• Есть ли использовать POST , когда вы должны сделать что - то , что чувствует RPC-как
• Есть ли использовать PUT для классов ресурсов, которые больше или иерархическая
• Как УДАЛИТЬ использование в предпочтении к POST для удаления ресурсов
• Do использовать GET для вещей , как расчеты, если ваш вклад не велик, в этом случае использование POST

Общие принципы проектирования веб-сервисов с HTTP:

• Не помещайте метаданные в тело ответа, который должен быть в заголовке
• Не помещайте метаданные в отдельный ресурс, если его включение не приведет к значительным накладным расходам
• Есть ли использовать соответствующий код состояния
  • 201 Createdпосле создания ресурса; ресурс должен существовать на момент отправки ответа
  • 202 Accepted после успешного выполнения операции или асинхронного создания ресурса
  • 400 Bad Requestкогда кто-то делает операцию с данными, которые явно поддельные; для вашего приложения это может быть ошибкой валидации; обычно резервируют 500 для неисследованных исключений
  • 401 Unauthorizedкогда кто-то обращается к вашему API без предоставления необходимого Authorizationзаголовка или когда учетные данные в нем Authorizationнедействительны; не используйте этот код ответа, если вы не ожидаете учетные данные через Authorizationзаголовок.
  • 403 Forbidden когда кто-то обращается к вашему API способом, который может быть вредоносным или если он не авторизован
  • 405 Method Not Allowed когда кто-то использует POST, когда он должен был использовать PUT и т. д.
  • 413 Request Entity Too Large когда кто-то пытается отправить вам неприемлемо большой файл
  • 418 I'm a teapot при попытке заваривать кофе с чайником
• Есть ли использование заголовков кэширования , когда вы можете
  • ETag заголовки хороши, когда вы можете легко уменьшить ресурс до значения хеша
  • Last-Modified Следует указать вам, что сохранение отметки времени обновления ресурсов - это хорошая идея.
  • Cache-Controlи Expiresдолжны быть даны разумные значения
• Сделайте все возможное, чтобы соблюдать заголовки кэширования в запросе ( If-None-Modified, If-Modified-Since)
• Do переадресовывает использовать , когда они имеют смысл, но они должны быть редкими для веб - службы

Что касается вашего конкретного вопроса, POST следует использовать для № 4 и № 5. Эти операции подпадают под "RPC-подобное" руководство выше. Для # 5, помните, что POST не обязательно должен использовать Content-Type: application/x-www-form-urlencoded. Это также может быть полезная нагрузка JSON или CSV.

Всякий раз, когда вам нужен новый глагол, подумайте о том, чтобы превратить этот глагол в существительное. Например, включите «активировать» в «активацию», а «подтвердить» в «проверка».

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

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

Что именно представляет «параметр»? Вероятно, ряд разных вещей, каждая из которых должна иметь отдельный ресурс, посвященный этому.

Другой способ добиться этого - когда вы обсуждаете свое приложение с конечными пользователями (теми, кто, вероятно, мало что знает о программировании), какие слова они часто используют сами?

Это те слова, которые вы должны разрабатывать вокруг приложения.

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

Я ничего не знаю о финансовом программном обеспечении, но если бы мне пришлось угадывать, я бы сказал, что некоторые ресурсы могут быть названы, например, «Отчет», «Оплата», «Перевод» и «Валюта».

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

Дизайн ваших URL не имеет ничего общего с тем, является ли ваше приложение RESTful или нет. Поэтому фраза «RESTful URLs» - это чепуха.

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

Тем не менее, давайте перейдем к вашему вопросу: последние два случая не являются RESTful и не вписываются в какую-либо схему отдыха. Это то, что вы могли бы назвать RPC. Если вы серьезно относитесь к REST, вам придется заново продумать, как ваше приложение работает с нуля. Либо так, либо откажитесь от REST и просто сделайте свое приложение как приложение RPC.

Хммм может и нет.

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

GET [parametersurl]/validationresults

POST [paramatersurl]
body: {command:"activate"}

Но опять же, эта активирующая вещь - RPC, а не REST.

Требования активации и проверки - это ситуации, когда вы пытаетесь изменить состояние ресурса. Не отличается то, что оформление заказа «выполнено», или какой-то другой запрос «отправлен». Существует множество способов смоделировать такие изменения состояния, но я считаю, что часто работает то, что нужно создавать ресурсы коллекций для ресурсов одного и того же состояния, а затем перемещать ресурс между коллекциями, чтобы влиять на состояние.

например, создать некоторые ресурсы, такие как,

/ActiveParameters
/ValidatedParameters

Если вы хотите сделать набор параметров активным, добавьте этот набор в коллекцию ActiveParameters. Вы можете передать набор параметров в виде тела объекта или передать URL-адрес в качестве параметра запроса следующим образом:

POST /ActiveParameters?parameter=/Parameters/{Id}

То же самое можно сделать с / ValidatedParameters. Если параметры недопустимы, сервер может вернуть «Bad Request» в запрос на добавление параметров в коллекцию проверенных параметров.

Я бы предложил следующий метаресурс и методы.

Сделайте параметры активными и / или подтвердите их:

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

Проверьте, являются ли параметры активными и действительными:

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<

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

Перво-наперво, что такое ОТДЫХ ?! REST или ReST акроним расшифровывается как «Передача состояния представления» и определяет обмен состоянием ресурса в определенном формате представления. Формат представления данных соответствует согласованному типу мультимедиа. В случаеapplication/html формата представления может быть поток форматированного текстового содержимого HTML, который отображается в браузере, вероятно, после применения некоторого форматирования таблицы стилей для позиционирования определенных элементов в определенных местоположениях.

В принципе, REST - это обобщение веб-браузера, доступного для просмотра, которое мы все знаем, хотя оно предназначено для всех видов приложений, а не только для браузеров. Следовательно, по своей конструкции те же понятия, которые применяются к сети, также применимы к архитектуре REST. Вопрос о том, как достичь чего-либо «RESTful», решается вокруг ответа на вопрос, как достичь чего-либо на веб-странице, а затем применить те же концепции на прикладном уровне.

Обычно веб-калькулятор может начинаться с некоторой «страницы», которая позволяет вводить некоторые значения для вычисления перед отправкой введенных данных на сервер. В HTML это обычно достигается с помощью <form>элементов HTML, которые обучают клиента доступным параметрам для установки, целевому местоположению для отправки запроса, а также формату представления, применяемому при отправке входных данных. Это может выглядеть так:

<html>
  <head>
    ...
  </head>
  <body>
    <form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
      <label for="firstNumber">First number:</label>
      <input type="number" id="firstNumber" name="firstNumber"/>

      <label for="secondNumber">Second number:</label>
      <input type="number" id="secondNumber" name="secondNumber"/>

      <input type="submit" value="Add numbers"/>
    </form>
  </body>
</html>

Пример выше, т.е. утверждает, что есть два поля ввода, которые могут быть заполнены пользователем или некоторыми другими автоматами, и что при вызове элемента ввода submit браузер заботится о форматировании входных данных в application/x-www-form-urlencodedотправляемом формате представления. в указанное целевое местоположение через указанный метод HTTP-запроса, POSTв этом случае. Если мы введем 1в firstNumberполе ввода и 2в secondNumberполе ввода, браузер сгенерирует представлениеfirstNumber=1&secondNumber=2 и отправит его как полезную нагрузку тела фактического запроса целевому ресурсу.

Исходный HTTP-запрос, выданный серверу, может выглядеть следующим образом:

POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html

firstNumber=1&secondNumber=2

Сервер может выполнить вычисление и ответить дополнительной HTML-страницей, которая содержит результат вычисления, поскольку запрос указал, что клиент понимает этот формат.

Как уже указывал Бретон, не существует такого понятия, как «RESTful» URL или URI. URI / URL - это своего рода вещь, которая не должна передавать никакого значения клиенту / пользователю. В приведенном выше примере с калькулятором пользователь просто не интересуется, куда ему отправлять данные, а просто заинтересован в том, чтобы при запуске поля ввода ввода отправлялся запрос. Вся необходимая информация, необходимая для выполнения задачи, должна быть уже предоставлена ​​сервером.

Браузер также может не знать, что запрос на самом деле заполняет калькулятор некоторыми входными параметрами, это также может быть какая-то форма заказа, которая возвращает только следующее представление формы для продолжения процесса заказа, или какой-то совершенно другой вид ресурс. Он просто выполняет то, что требует спецификация HTML в таком случае, и его не волнует, что на самом деле делает сервер. Эта концепция позволяет браузеру использовать один и тот же формат представления для выполнения самых разных задач, таких как заказ некоторых вещей из предпочитаемого вами интернет-магазина, общение с лучшими друзьями, вход в учетную запись онлайн и т. Д.

Affordance некоторых элементов, например в случае ввода представить поле, которое обычно переводится как кнопка, определяет то , что вы должны , чтобы с ним. В случае кнопки или ссылки она в основном говорит вам нажать на нее. Другие элементы могут передавать различные возможности. Такая доступность также может быть выражена через отношенияpreload ссылок, то есть с аннотированными ссылками, которые в основном говорят клиенту, что он уже может загружать контент связанного ресурса в фоновом режиме, поскольку пользователь, скорее всего, будет захватывать этот контент следующим. Такие отношения ссылок, конечно, должны быть стандартизированы или следовать механизму расширения для типов отношений, как это определено в веб-ссылках .

Это фундаментальная концепция, которая используется в Интернете, и которая также должна использоваться в архитектуре REST. По словам «дяди Боба» Роберта К. Мартина , архитектура имеет намерение, а за архитектурой REST подразумевается разделение клиентов от серверов, чтобы позволить серверам в будущем развиваться свободно, не опасаясь, что они сломают клиентов. Это, к сожалению, требует большой дисциплины, так как очень легко внедрить связывание или добавить быстрые решения, чтобы выполнить работу и двигаться дальше. Как отметил Джим Уэббер в архитектуре REST, вам, как поставщику услуг, следует попытаться разработать протокол приложения домена, похожий на текстовую компьютерную игру 70-х годов, которую клиенты будут выполнять до тех пор, пока не достигнут конца процесса.

К сожалению, на самом деле множество так называемых API-интерфейсов REST делают все, кроме этого. Вы видите обмен в основном данными на основе JSON, который указан в специальной документации API, которую обычно сложно динамически интегрировать на лету. Формат, которым должен выглядеть запрос, также жестко запрограммирован во внешнюю документацию, что приводит к множеству интерпретаций URI, возвращающих предопределенные типы.вместо использования какого-либо общего формата представления, который согласовывается заранее. Это предотвращает изменение серверов, поскольку клиенты теперь ожидают получить определенный формат данных (обратите внимание, не формат представления!) Для предопределенных URI. Кроме того, этот обмен пользовательским форматом данных не позволяет клиентам взаимодействовать с другими API, поскольку «формат данных» обычно связан с конкретным API. Мы знаем эту концепцию из прошлых технологий RPC, таких как Corba, RMI или SOAP, которые мы осуждаем как что-то злое, хотя Peppol перешел к нему снова, заменив AS2 на AS4 в качестве протокола передачи по умолчанию с недавнего времени.

Что касается заданного вопроса, отправка данных в виде CSV-файла ничем не отличается от использования application/x-www-form-urlencodedпредставления или аналогичного материала. Джим Уэббер ясно дал понять, что в конце концов HTTP - это всего лишь транспортный протокол, предметной областью которого является передача документов через Интернет . Клиент и сервер должны как минимум поддерживать оба, text/csvкак определено в RFC 7111 . Этот CSV-файл может быть сгенерирован как следствие обработки типа мультимедиа, который определяет элементы формы, целевой элемент или атрибут для отправки запроса, а также метод HTTP для выполнения загрузки конфигурации.

Существует несколько типов мультимедиа, которые поддерживают такие формы, как HTML , HAL Forms , halform , ion или Hydra . Однако в настоящее время я не знаю, какой тип носителя может автоматически кодировать входные данные text/csvнапрямую, поэтому может потребоваться определить его и зарегистрировать в реестре типов носителей IANA. .

Я думаю, что загрузка и выгрузка полного набора параметров не должны быть проблемой. Как упоминалось ранее, целевой URI не имеет значения, так как клиент будет использовать URI только для извлечения нового контента для обработки. Фильтрация по бизнес-дате также не должна быть сложной. Здесь сервер должен, однако, клиент со всеми возможностями, которые клиент может просто выбрать. В последние годы развились GraphQL и RestQL, которые представили язык, похожий на SQL, который может быть нацелен на определенную конечную точку для получения отфильтрованного ответа. Однако в истинном смысле REST это нарушает идею, лежащую в основе REST: a) GraphQL, т. Е. Использует только одну конечную точку, которая каким-то образом препятствует оптимальному использованию кэширования; к базовой модели данных ресурса.

Активация или деактивация определенных параметров конфигурации - это просто вопрос запуска элементов управления гипермедиа, которые предоставляют эту возможность. В HTML-формах это может быть простой флажок или многострочный выбор в списке или тому подобное. В зависимости от формы и того, какой метод он определяет, он может затем отправить всю конфигурацию с помощью PUTили быть осведомленным о внесенных изменениях и выполнить только частичное обновление с помощью PATCH. Последний требует в основном вычисления представления изменения к обновленному и передает серверу необходимые шаги для преобразования текущего представления в желаемое. В соответствии со спецификацией PATH это должно быть сделано внутри транзакции, чтобы выполнялись все или ни один из шагов.

HTTP позволяет и рекомендует серверу проверять полученный запрос заранее, прежде чем применить изменения. Для PUT спецификация гласит:

Исходный сервер ДОЛЖЕН проверить, что представление PUT соответствует любым ограничениям, которые имеет сервер для целевого ресурса, который не может или не будет изменен PUT. Это особенно важно, когда исходный сервер использует внутреннюю информацию о конфигурации, связанную с URI, чтобы установить значения для метаданных представления в ответах GET. Когда представление PUT несовместимо с целевым ресурсом, исходный сервер ДОЛЖЕН либо сделать их согласованными, преобразовав представление или изменив конфигурацию ресурса, либо ответить соответствующим сообщением об ошибке, содержащим достаточную информацию, чтобы объяснить, почему представление не подходит. Предлагаются коды состояния 409 (конфликт) или 415 (неподдерживаемый тип носителя),

Например, если целевой ресурс всегда настроен на использование Content-Type «text / html», а представление, представляющее собой PUT, имеет Content-Type «image / jpeg», исходный сервер должен выполнить одно из следующих действий:

а. перенастроить целевой ресурс для отражения нового типа носителя;

б. преобразовать представление PUT в формат, соответствующий формату ресурса, перед сохранением его в качестве нового состояния ресурса; или,

с. отклоните запрос с ответом 415 (неподдерживаемый тип носителя), указывающим, что целевой ресурс ограничен «text / html», возможно, включающим ссылку на другой ресурс, который будет подходящей целью для нового представления.

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

Чтобы подвести итог этой публикации, вы должны либо использовать существующий тип мультимедиа, который позволяет обучить клиента обязательным или поддерживаемым входным параметрам, целевому местоположению, на которое следует отправить запрос, операции, которую необходимо использовать, а также типу мультимедиа запрос должен быть отформатирован или указан ваш собственный, который вы регистрируете в IANA. Последнее может быть необходимо, если вы хотите преобразовать входные данные вtext/csvа затем загрузить представление CSV на сервер. Проверка должна произойти до того, как изменения будут применены к ресурсу. Фактический URI не должен быть релевантным для клиентов, кроме как для определения, куда отправить запрос и, как таковой, может быть свободно выбран вами, разработчиком сервиса. Выполнив эти шаги, вы в значительной степени получите свободу менять свою серверную часть в любое время, и клиенты не сломаются, как следствие, если они будут поддерживать используемые типы носителей.

Редактировать: Действительно, URI не позволил бы GETзапросам оставаться идемпотентными.

Однако для проверки использование кодов состояния HTTP для уведомления о действительности запроса (для создания нового или изменения существующего «параметра») будет соответствовать модели Restful.

Сообщите с 400 Bad Requestкодом состояния, если предоставленные данные являются / являются недействительными и запрос должен быть изменен перед повторной отправкой ( коды состояния HTTP / 1.1 ).

Это зависит от проверки во время представления, а не откладывания, как в вашем случае использования. Другие ответы имеют подходящие решения для этого сценария.

В среде REST каждый URL является уникальным ресурсом. Каковы ваши ресурсы? Финансовый калькулятор действительно не имеет никаких очевидных ресурсов. Вам нужно покопаться в том, что вы называете параметрами, и вытащить ресурсы. Например, календарь погашения кредита может быть ресурсом. URL-адрес календаря может включать дату начала, срок (в месяцах или годах), период (когда начисляются проценты), процентную ставку и начальный принцип. Со всеми этими значениями у вас есть определенный календарь платежей:

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000

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