動詞を使わずに REST URL を作成するにはどうすればよいですか?

https://stackoverflow.com/questions/1619152

06-07-2019
|

質問

RESTful URL をどのように設計するかを決めるのに苦労しています。私は動詞ではなく名詞を含む URL を使用するという穏やかなアプローチに賛成ですが、その方法がわかりません。

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

新しいパラメータをアップロードする
最新のパラメータを取得する
指定された営業日のパラメータを取得する
一連のパラメータをアクティブにする
パラメータのセットを検証する

安静なアプローチは、次のタイプの URL を使用することだと思います。

/parameters
/parameters/12-23-2009

最初の 3 つの使用例は、次のように実現できます。

POST では、POST リクエストにパラメータファイルを含めます。
最初のURLのGET
2番目のURLのGET

しかし、動詞なしで 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 スペースを可能な限り制限する
するパスセグメントを短く保つ
するどちらかを好む /resource または /resource/;使用しないリダイレクトから 301 リダイレクトを作成する
するリソースのサブ選択にはクエリパラメータを使用します。つまりページネーション、検索クエリ
する HTTP ヘッダーまたは本文に含めるべきものを URI から移動します。

（注記：私は「RESTful URI 設計」とは言いませんでした。REST では URI は基本的に不透明です。)

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

やめてください 状態を変更するには GET を使用してください。これは、Googlebot に一日を台無しにする素晴らしい方法です
やめてください リソース全体を更新しない場合は PUT を使用してください
やめてください 同じ URI に対して正当に GET も実行できる場合を除き、PUT を使用してください。
やめてください POST を使用して、有効期間が長い情報、またはキャッシュすることが適切な情報を取得します。
やめてください そうでない操作を実行する冪等 PUTあり
する可能な限りGETを使用する
する疑わしい場合は、PUT ではなく POST を使用してください
する RPC っぽいことをする必要があるときは、必ず POST を使用してください。
するより大きなリソースまたは階層的なリソースのクラスには PUT を使用します。
するリソースを削除するには、POST ではなく DELETE を使用してください
する入力が大きい場合を除き、計算などには GET を使用します。その場合は POST を使用します。

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

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

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

新しい動詞が必要なように見えるときはいつでも、その動詞を名詞に変えることを考えてください。たとえば、「アクティベート」を「アクティベーション」に、「検証」を「検証」に変更します。

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

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

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

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

これらは、アプリケーションを設計する際に必要な単語です。

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

金融ソフトウェアについては何も知りませんが、推測しなければならない場合、「レポート」、「支払い」、「送金」、「通貨」などの名前でリソースの一部が移動する可能性があると思います;。

ソフトウェア設計プロセスのこの部分に関する多くの優れた書籍があります。推奨できる2つはドメインドリブンデザインおよび分析パターン。

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

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

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

おそらく、そうではありません。

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

get [parametersurl] / validationresults

投稿[paramatersurl]

body：{command：＆quot; activate＆quot;}

しかし、そのアクティベートはRESTではなくRPCです。

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

e.g。次のようなリソースを作成します。

/ActiveParameters
/ValidatedParameters

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

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

/ ValidatedParametersでも同じことができます。パラメータが無効な場合、サーバーは＆quot; Bad Request＆quot;を返すことができます。検証済みパラメーターのコレクションにパラメーターを追加する要求に追加します。

次のメタリソースとメソッドを提案します。

パラメーターをアクティブにする、および/または検証する：

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

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

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

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

編集：実際、URIにより、 GET リクエストがべき等性のままになることはありません。

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

送信されたデータが無効であり、再送信する前にリクエストを変更する必要がある場合は、 400 Bad Request ステータスコードでレポートを返します（ HTTP / 1.1ステータスコード）。

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

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow