70

リソースとして最適に表現されていないように見えるものがあるとします (一時停止したいプロセスのステータス、サーバーで実行したいステートレスな計算など)。

API 設計でどちらかを使用する場合、process/123/pauseそれcalculations/fibonacciは基本的に REST と互換性がないのでしょうか? これらの URL が HATEOAS を使用して検出可能であり、メディア タイプが標準化されている限り、私が読んだものとはかけ離れているようです。

または、ここで回答したようにメッセージにアクションを入れた方がいいですか?

注 1:
私の例のいくつかを名詞で言い換えることができることは理解しています。ただし、特定のケースでは、名詞は動詞ほど機能しないと感じています。したがって、これらの動詞を使用するとすぐに非RESTfulになるかどうかを理解しようとしています。もしそうなら、なぜその推奨事項がそれほど厳格なのか、そしてそのような場合にそれに従わないことで私が見逃す可能性のある利点.

注2：「RESTには制約がありません」という
回答は有効な回答です（これは、このアプローチがRESTfulであることを意味します）。「誰に質問するかによる」または「ベスト プラクティスです」という回答は、実際には質問への回答ではありません。この質問は、REST の概念が、2 人が同じ制約のセットを参照するために使用できる明確に定義された一般的な用語として存在することを前提としています。仮定自体が間違っていて、REST の正式な議論が無意味である場合は、そう言ってください。

4

4 に答える 4

42

この記事にはいくつかのヒントがあります: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

記事からの引用：

CRUD 操作の世界に当てはまらないアクションについてはどうでしょうか?

これは、物事が曖昧になる可能性がある場所です。いくつかのアプローチがあります。

  1. リソースのフィールドのように見えるようにアクションを再構築します。これは、アクションがパラメーターを取らない場合に機能します。たとえば、アクティブ化アクションをブール値のアクティブ化フィールドにマップし、PATCH を介してリソースに更新することができます。

  2. RESTful 原則を備えたサブリソースのように扱います。たとえば、GitHub の API では、PUT /gists/:id/star で Gist にスターを付け、DELETE /gists/:id/star でスターを外すことができます。

  3. アクションを適切な RESTful 構造にマッピングする方法が本当にない場合があります。たとえば、複数リソースの検索を特定のリソースのエンドポイントに適用しても意味がありません。この場合、/search は名詞ではありませんが、最も意味があります。これは問題ありません。API コンシューマの観点から正しいことを行い、混乱を避けるために明確に文書化されていることを確認してください。

私は個人的に提案＃2が好きです。何かを一時停止する必要がある場合、何を一時停止していますか? 名前付きのプロセスの場合は、次を試してください。

/process/{processName}/pause
于 2013-10-29T03:13:35.710 に答える
41

厳密には名詞と動詞の違いではありません。それはあなたが次のことをしているかどうかです：

  • リソースの識別
  • 表現によるリソースの操作

リソースとは フィールディングはそれを次のように定義します。

REST における情報の重要な抽象化はリソースです。名前を付けることができるすべての情報はリソースである可能性があります: ドキュメントまたは画像、一時的なサービス (「ロサンゼルスの今日の天気」など)、他のリソースのコレクション、非仮想オブジェクト (人物など) など。 . 言い換えれば、著者のハイパーテキスト参照の対象となる可能性のある概念は、リソースの定義に適合する必要があります。リソースは一連のエンティティへの概念的なマッピングであり、特定の時点でのマッピングに対応するエンティティではありません。」

さて、あなたの質問に。URL を見て、「これこれの URL は基本的に REST と互換性がないのですか?」と言うだけではいけません。REST システムの URL はそれほど重要ではないからです。URLprocess/123/pauseとcalculations/fibonacci上記の定義によってリソースを識別することがより重要です。そうであれば、REST 制約違反はありません。そうでない場合は、REST の統一インターフェイスの制約に違反しています。あなたの例は、それがリソース定義に適合しないため、この制約に違反すると私に信じさせます。

このシステムでリソースが何であるかを説明するために、プロセスをpaused-processesリソース コレクションに POST することでプロセスのステータスを変更できます。これはおそらくプロセスを操作する珍しい方法ですが、REST アーキテクチャ スタイルと根本的に互換性がないわけではありません。

計算の場合、計算自体がリソースである可能性があり、そのリソースは次のようになります。

Request:
GET /calculations/5

Response:
{
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607
}

繰り返しますが、これはリソースのやや変わった概念です。もう少し典型的な使用法は次のようになると思います。

Request:
GET /stored-calculations/12381728 (note that URL is a random identifier)

Response:
{
  number: 5,
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607
}

おそらく、誰でも電卓で実行できる完全な計算以外に、そのリソースに関する追加情報を保存したいと思うでしょう...

Response:
{
  number: 5,
  fibonacci: 5,
  prime-number: true,
  square-root: 2.23607,
  last-accessed-date: 2013-10-28T00:00:00Z,
  number-of-retrievals-of-this-resource: 183
}
于 2013-10-29T05:22:36.067 に答える