292

安らかな 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

??

4

9 に答える 9

1001

適切な URI 設計の一般原則:

  • クエリ パラメータを使用して状態を変更しないでください
  • 可能であれば、大文字と小文字が混在するパスを使用しないでください。小文字がベスト
  • URI で実装固有の拡張子を使用しないでください (.php、.py、.pl など)。
  • URI でRPCに陥らないでください
  • 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 UnauthorizedAuthorization誰かが必要なヘッダーを提供せずに API にアクセスした場合、または 内の資格情報Authorizationが無効な場合。Authorizationヘッダー経由で資格情報を期待していない場合は、この応答コードを使用しないでください。
  • 403 Forbidden誰かが悪意のある方法で API にアクセスした場合、または承認されていない場合
  • 405 Method Not AllowedPUT を使用する必要がある場合に POST を使用する場合など
  • 413 Request Entity Too Large誰かが容認できないほど大きなファイルを送信しようとしたとき
  • 418 I'm a teapot ティーポットでコーヒーを淹れるとき
  • 可能な限りキャッシングヘッダーを使用してください
  • ETagヘッダーは、リソースをハッシュ値に簡単に変換できる場合に適しています
  • Last-Modifiedリソースが更新されたときのタイムスタンプを保持することをお勧めします。
  • Cache-ControlExpires適切な値を与える必要があります
  • リクエストのキャッシング ヘッダーを尊重するためにできる限りのことを行う(If-None-Modified , If-Modified-Since)
  • 意味のある場合はリダイレクトを使用しますが、これは Web サービスではまれです。

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

于 2009-10-25T01:20:27.043 に答える
73

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

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

{ "active": true }
于 2009-10-24T21:34:30.320 に答える
18

新しい動詞が必要だと思われるときはいつでも、代わりにその動詞を名詞に変えることを考えてください。たとえば、'activate' を 'activation' に、'validate' を 'validation' に変えます。

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

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

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

これを理解するもう 1 つの方法は、アプリケーションについてエンド ユーザー (プログラミングについてほとんど知らないと思われるユーザー) と話し合うときに、彼ら自身が繰り返し使用する言葉は何ですか?

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

潜在的なユーザーとまだこの変換を行っていない場合は、今すぐすべてを停止し、完了するまで別のコード行を書かないでください。そうして初めて、チームは何を構築する必要があるかについてのアイデアを得ることができます。

私は金融ソフトウェアについて何も知りませんが、推測する必要がある場合、リソースのいくつかは「レポート」、「支払い」、「転送」、「通貨」などの名前で呼ばれていると思います.

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

于 2009-10-24T22:54:18.557 に答える
6

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

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

/ActiveParameters
/ValidatedParameters

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

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

/ValidatedParametersでも同じことができます。パラメータが有効でない場合、サーバーは「不正な要求」を要求に返し、検証されたパラメータのコレクションにパラメータを追加できます。

于 2009-10-25T03:19:18.067 に答える
1

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

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

> 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': '...'}
< }
<
于 2009-10-24T21:34:18.387 に答える
0

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

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

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

ただし、これは、ユースケースのように延期するのではなく、送信時の検証に依存しています。他の回答には、そのシナリオに対する適切な解決策があります。

于 2009-10-24T21:27:39.817 に答える
0

REST 環境では、各 URL は一意のリソースです。あなたのリソースは何ですか？金融計算機には、明らかなリソースはまったくありません。パラメータを呼び出しているものを掘り下げて、リソースを引き出す必要があります。たとえば、ローンの償却カレンダーはリソースである可能性があります。カレンダーの URL には、開始日、期間 (月または年)、期間 (複利の場合)、利率、および元本が含まれる場合があります。これらすべての値を使用して、特定の支払いカレンダーがあります。

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

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

于 2009-10-24T22:57:12.000 に答える