web-dev-qa-db-ja.com

動詞なしでREST URLを作成する方法は？

安らかなURLを設計する方法を決定するのに苦労しています。私は、動詞ではなく名詞でURLを使用する安らかなアプローチに賛成しています。これを行う方法は理解できません。

金融計算機を実装するサービスを作成しています。計算機は、CSVファイルを介してアップロードする一連のパラメーターを受け取ります。ユースケースには次のものが含まれます。

  1. 新しいパラメーターをアップロードする
  2. 最新のパラメーターを取得する
  3. 特定の営業日のパラメーターを取得する
  4. パラメータのセットをアクティブにします
  5. 一連のパラメーターを検証する

安らかなアプローチは、次のタイプのURLを持つことです。

/parameters
/parameters/12-23-2009

次の3つのユースケースを達成できます。

  1. POST要求にパラメーターファイルを含めるPOST
  2. 最初のURLのGET
  3. 2番目のURLのGET

しかし、動詞なしで4番目と5番目のユースケースをどのように行いますか？次のようなURLは必要ありませんか？

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

？

restrestful-url
276
Marcus Leon

おそらく次のようなもの：

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

{ "active": true }
71
yfeldblum

適切なURIデザインの一般原則：

  • 禁止クエリパラメータを使用して状態を変更する
  • しないでくださいあなたがそれを助けることができるなら、大文字と小文字が混在するパスを使用してください。小文字が最適です
  • しないでくださいURI（.php、.py、.plなど）で実装固有の拡張機能を使用してください
  • Do n'tはURIで RPC に分類される
  • DoURIスペースをできるだけ制限する
  • Doパスセグメントを短く保つ
  • Do/resourceまたは/resource/のいずれかを優先します;使用しないものから301リダイレクトを作成する
  • Doは、リソースのサブ選択にクエリパラメータを使用します。つまり、ページネーション、検索クエリ
  • DoHTTPヘッダーまたは本文にあるべきURIからものを移動する

（注：「RESTful URI design」とは言いませんでした。RESTではURIは本質的に不透明です。）

HTTPメソッド選択の一般原則：

  • Do n'tGETを使用して状態を変更しないでください。これは、Googlebotがあなたの一日を台無しにする素晴らしい方法です
  • リソース全体を更新しない限り、PUTを使用しないでください
  • DUT't同じURIで合法的にGETを実行できる場合を除き、PUTを使用しない
  • しないPOSTを使用して、長命の情報またはキャッシュに適する情報を取得します
  • しないPUTで idempotent ではない操作を実行する
  • Do可能な限りGETを使用する
  • Do疑わしい場合はPUTよりもPOSTを優先的に使用します
  • DoRPCに似た何かをする必要があるときはいつでもPOSTを使用する
  • Doより大きなまたは階層的なリソースのクラスにPUTを使用する
  • DoPOSTに優先してDELETEを使用してリソースを削除します
  • Do入力が大きい場合を除き、計算などにGETを使用します。その場合、POSTを使用します

HTTPを使用したWebサービス設計の一般原則：

  • Do n'tヘッダーにあるべき応答の本文にメタデータを入れる
  • 禁止メタデータを含めると、大きなオーバーヘッドが発生しない限り、メタデータを別のリソースに配置する
  • Do適切なステータスコードを使用する
    • リソースを作成した後の201 Created。リソースmustは、応答の送信時に存在する必要があります
    • 操作を正常に実行した後、またはリソースを非同期で作成した後の202 Accepted
    • 400 Bad Request誰かが明らかに偽のデータに対して操作を行ったとき。アプリケーションの場合、これは検証エラーである可能性があります。通常、キャッチされない例外用に500を予約します
    • 401 Unauthorizedは、誰かが必要なAuthorizationヘッダーを提供せずにAPIにアクセスした場合、またはAuthorization内の資格情報が無効な場合。 Authorizationヘッダーを介した資格情報を期待していない場合は、この応答コードを使用しないでください。
    • 403 Forbiddenは、誰かが悪意のある方法でAPIにアクセスした場合、または許可されていない場合
    • 405 Method Not Allowed誰かがPOSTを使用する場合、PUTなどを使用する必要がある場合
    • 413 Request Entity Too Large誰かが容認できないほど大きなファイルを送ろうとしたとき
    • 418 I'm a teapotティーポットでコーヒーを入れようとする場合
  • Doできる限りキャッシュヘッダーを使用する
    • ETagヘッダーは、リソースをハッシュ値に簡単に削減できる場合に適しています
    • Last-Modifiedは、リソースが更新されたときのタイムスタンプを保持することをお勧めします。
    • Cache-ControlおよびExpiresには適切な値を指定する必要があります
  • Doリクエスト内のヘッダーのキャッシュを尊重するためにできることすべて（If-None-Modified、If-Modified-Since）
  • Do理にかなっている場合はリダイレクトを使用しますが、Webサービスではこれらはまれです

特定の質問に関しては、POSTを＃4と＃5に使用する必要があります。これらの操作は、上記の「RPCのような」ガイドラインに該当します。 ＃5の場合、POSTは必ずしもContent-Type: application/x-www-form-urlencodedを使用する必要がないことに注意してください。これは、JSONまたはCSVペイロードと同じくらい簡単にできます。

982
Bob Aman

新しい動詞が必要と思われる場合は、その動詞を名詞に変えることを検討してください。たとえば、「アクティベート」を「アクティベーション」に、「検証」を「検証」に変更します。

しかし、あなたが書いたことから、あなたのアプリケーションにはもっと大きな問題があると思います。

「パラメータ」と呼ばれるリソースが提案されるたびに、すべてのプロジェクトチームメンバーの心に危険信号を送信する必要があります。 「パラメータ」は文字通りあらゆるリソースに適用できます。それは十分に具体的ではありません。

「パラメーター」とは正確に何を表していますか？おそらくさまざまなものがあり、それぞれに専用のリソースが必要です。

これを実現する別の方法-アプリケーションをエンドユーザー（おそらくプログラミングについてほとんど知らない人）と話し合うとき、彼ら自身が繰り返し使用する言葉は何ですか？

これらは、アプリケーションを設計するときに使用する必要がある言葉です。

見込み客とのこの変換をまだ行っていない場合は、すぐにすべてを停止し、実行するまで別のコード行を記述しないでください！そうしてはじめて、チームは何を構築する必要があるかを知ることができます。

金融ソフトウェアについては何も知りませんが、推測しなければならない場合、リソースの一部は「レポート」、「支払い」、「振替」、「通貨」などの名前で行くかもしれません。

ソフトウェア設計プロセスのこの部分に関する多くの優れた本があります。推奨できる2つは、 ドメイン駆動設計 と 分析パターン です。

18
Rich Apodaca

URLの設計は、アプリケーションがRESTfulかどうかとは関係ありません。したがって、「RESTful URLS」というフレーズはナンセンスです。

RESTが実際に何であるかについて、さらに読む必要があると思います。 RESTはURLを不透明として扱います。そのため、動詞、名詞、その他何が含まれているかはわかりません。それでもURLを設計したいかもしれませんが、それはRESTではなくUIについてです。

それでは、あなたの質問に行きましょう。最後の2つのケースはRESTfulではなく、どのような安らかなスキームにも適合しません。これらはRPCと呼ばれるものです。 RESTを真剣に考えている場合は、アプリケーションがどのように機能するかを一から考え直す必要があります。または、RESTを放棄して、アプリをRPCアプリとして実行します。

多分そうではありません。

ここでの考え方は、すべてをリソースとして扱う必要があるということです。したがって、一連のパラメーターに参照できるURLがあれば、追加するだけです。

[parametersurl]/validationresultsを取得します

投稿[paramatersurl]

body：{command： "activate"}

繰り返しになりますが、そのアクティベートはRESTではなくRPCです。

11
Breton

アクティブ化および検証の要件は、リソースの状態を変更しようとしている状況です。注文を「完了」したり、他のリクエストを「送信」したことも同じです。これらの種類の状態変化をモデル化する方法は多数ありますが、同じ状態のリソースのコレクションリソースを作成してから、コレクション間でリソースを移動して状態に影響を与えることがよくあることです。

例えば次のようなリソースを作成します。

/ActiveParameters
/ValidatedParameters

パラメーターのセットをアクティブにしたい場合は、そのセットをActiveParametersコレクションに追加します。次のように、一連のパラメーターをエンティティ本体として渡すか、URLをクエリパラメーターとして渡すことができます。

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

/ ValidatedParametersでも同じことができます。パラメータが有効でない場合、サーバーはリクエストに「Bad Request」を返して、検証済みパラメータのコレクションにパラメータを追加できます。

6
Darrel Miller

次のメタリソースとメソッドをお勧めします。

パラメータをアクティブにするか、検証します：

> 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': '...'}
< }
<
1
Andrey Vlasovskikh

REST環境では、各URLは一意のリソースです。あなたのリソースは何ですか？財務計算機には、明らかなリソースはありません。パラメーターを呼び出しているものを掘り下げ、リソースを引き出す必要があります。たとえば、ローンの償却カレンダーがリソースになる場合があります。カレンダーのURLには、start_date、期間（月または年単位）、期間（利息が複利される場合）、金利、および初期原則が含まれる場合があります。これらのすべての値を使用すると、特定の支払いカレンダーがあります。

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

今、私はあなたが何を計算しているのかわかりませんが、パラメータリストの概念はRESTfulに聞こえません。他の誰かが言ったように、上記の要件はよりXMLRPCに聞こえます。 RESTを探している場合は、名詞が必要です。計算は名詞ではなく、名詞に作用する動詞です。計算から名詞を引き出すには、向きを変える必要があります。

0
jmucchiello

編集：実際、URIはGETリクエストがべき等性のままになるのを防いでいたでしょう。

ただし、検証では、HTTPステータスコードを使用して要求の有効性を通知する（新しいパラメータを作成するか、既存の「パラメータ」を変更する）ことは、Restfulモデルに適合します。

送信されたデータが無効であり、再送信する前にリクエストを変更する必要がある場合は、400 Bad Requestステータスコードで報告してください（ HTTP/1.1 Status Codes ）。

ただし、これは、ユースケースのように遅延するのではなく、送信時に検証することに依存しています。他の回答には、そのシナリオに適したソリューションがあります。

0
Derek Mortimer