緩やかなエンドポイント命名規則

Question

RESTエンドポイントは動詞の代わりに名詞でなければならないが、時にはわずかな偏差が許されることは知っていますか？

製品を公開するエンドポイントを想像してください（ウェブページに表示するか、キューに何かを追加するなど）。

私はこれを解決する2つの方法を考え出すことができます。

1）PUT api/products/1/publish - 私はそれが明白であり、バックエンドの複雑さを避け、それを自ら文書化するので、好きです。

2）PATCH/PUT/PATCHのAPI /製品/ 1

{ 
    "color": "green", 

    //some properties removed for brevity 

    "ispublished" : true 
} 

第2のアプローチは、ポスト本体にisPublishedフィールドを追跡するためにバックエンドサービスを必要とし、それが本当のスタートに反転したとき出版プロセス。これは少し複雑でより多くのメンテナンスを感じます。

私の質問は、RESTの観点からは最初のアプローチを使用するのはいいですか？いくつかの大きな欠点がありますか？

Answer 1

技術的には RPCスタイルに従って、URLで動詞を使用するのを止めるものは何もありません。 概念的にはですが、これはRESTがどのように設計されているのかとは異なります。

RESTは再プレゼンテーションSテートT ransferの略です。このアーキテクチャスタイルはresource-orientedであり、プロトコルに依存しませんが、HTTPプロトコルで実装されるのはであり、頻繁にはです。

HTTPプロトコルでRESTアプリケーションを実装する場合、リソースはURIで識別され、そのリソースに対する操作はHTTP methods（他の動詞は必要ありません）で表されます。リソースの状態を変更するには、リソースの新しい状態の表現をサーバーに送信する必要があります。表現は、JSON、XML、またはリソースの状態を表すことができるその他の形式にすることができます。

5.2.1.2 Representations

RESTコンポーネントは、そのリソースの現在のまたは意図の状態をキャプチャするために表現を使用し、コンポーネント間のその表現を転送することにより、リソースに対してアクションを実行します。以下の引用文を参照してください。表現は、バイトのシーケンスと、それらのバイトを記述する表現メタデータです。表現に一般的に使用されますが正確ではない名前には、文書、ファイル、HTTPメッセージエンティティ、インスタンス、またはバリアントがあります。

[...]与えられた表現が[...]要求されたリソースの現在の状態、要求されたリソースのための所望の状態、またはいくつかの他のリソースの値を示してもよい

続いアプローチでは、productリソースはstatusサブリソースを持つことができます。あなたのニーズに応じて、draft,published,inactiveなど、statusは異なる値を持つことができます。

そして、要求ペイロードで送信されたJSONでstatusサブリソースの状態を置き換えるためにPUTを使用：「公表」

PUT /api/products/1/status HTTP/1.1 
Host: example.org 
Content-Type: application/json 

{ 
    "value" : "published" 
}