RESTful URL の設計方法を決めるのに苦労しています。動詞ではなく名詞を含む URL を使用する RESTful アプローチには賛成ですが、その方法がわかりません。
私たちは金融計算機を実装するサービスを作成しています。計算機は、CSV ファイル経由でアップロードする一連のパラメータを受け取ります。使用例は次のとおりです。
- 新しいパラメータをアップロードする
- 最新のパラメータを取得する
- 指定された営業日のパラメータを取得する
- パラメータセットをアクティブにする
- パラメータセットを検証する
RESTful なアプローチとしては、次のタイプの URL を使用するのがよいでしょう。
/parameters
/parameters/12-23-2009
最初の 3 つのユースケースは、次の方法で実現できます。
- POSTリクエストにパラメータファイルを含めるPOST
- 最初のURLのGET
- 2番目のURLのGET
しかし、動詞なしで 4 番目と 5 番目のユースケースを実行するにはどうすればよいでしょうか? 次のような URL が必要ではないでしょうか。
/parameters/ID/activate
/parameters/ID/validate
??
ベストアンサー1
適切な URI 設計のための一般原則:
- クエリパラメータを使用して状態を変更しないでください
- 可能であれば、大文字と小文字が混在したパスは使用しないでください。小文字がベストです。
- URI では実装固有の拡張子 (.php、.py、.pl など) を使用しないでください。
- 陥らないようにRPCURIで
- 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 ペイロードでも同様に簡単に使用できます。