REST と HTTP セマンティクス

Roy Fielding は博士論文として REST を作成しました。 

これを読んだ後、次の 3 つの基本要素に要約されます。

1. オブジェクトの統計を説明するドキュメント

2. システム間でオブジェクトの状態をやり取りするトランスポート メカニズム

3. 状態に対して実行する一連の操作

Roy は HTTP のみに焦点を当てていましたが、別のトランスポートを使用できない理由がわかりません。以下に例をいくつか示します。

• WebDAV 共有をマウントします（WebDAV は HTTP 拡張機能であるため、引き続き HTTP を使用します）。スプレッドシート (.xls、.xlsx、.csv、.ods) をマウントされたフォルダーにコピーします。各行は新規/更新された状態になります。共有にコピーする行為は更新/挿入操作を示し、ファイル名はデータの種類を示し、列はフィールドを示します。サーバーは、(ドキュメント名)-ステータス.(ドキュメントサフィックス) で応答します。これにより、各行のキー、ステータス、および場合によってはエラー メッセージが提供されます。この場合、データをリクエストすることはあまり意味がありません。

• gRPC を使用します。送信されるオブジェクトはドキュメント、HTTP はトランスポート、リモート メソッドの名前は操作です。データは提供と要求の両方が可能です。

• FTP を使用します。 WebDAV と同様に、ファイルベースです。 PUT コマンドは更新/挿入であり、GET コマンドはリクエストです。 GET はファイル名のみを提供するため、通常は指定されたタイプのすべてのデータを提供します。データのサブセットを取得するためのハードコーディングされたフィルタを示す特別なファイル名を許可することができます。

実際の REST 実装を見ると、基本的な HTTP に従っていないことがよくあります。セマンティクス、そして私はこれについて与えられた説明を見たことがありません、たださまざまな意見が集まっているだけです。私が見つけたものはどれも RFC を参照していませんでした。ほとんどの人は、

• POST = 作成

• PUT = ドキュメント全体を更新

• PATCH = ドキュメントの一部を更新します

• GET = ドキュメント全体を取得します

これは、POST と PUT に関する HTTP の状態に反しています。 :

• PUT は「作成」または「更新」です。 GET は通常、最後に PUT されたものを返します。 PUT が作成する場合は、201 Created を返さなければなりません。 PUT が更新する場合は、200 OK または 204 No Content を返さなければなりません。 RFC では、PUT の 200 OK の内容がアクションのステータスであるべきであると提案しています。 SQL の場合、select ステートメントから新しい行を返すのは問題ないと思います。これには、生成された列が個別の GET を実行することなく呼び出し元に返されるという利点があります。

• POST は、独自のセマンティクスに従ってリソースを処理します。古い RFC では、POST はリソースの下位のものであると述べられていました。すべてのバージョンで、メーリング リストに記事を投稿する例が示されています。すべてのバージョンでは、リソースが作成された場合は 201 Created が返されるべきであるとされています。

私は、実質的に POST の実際の意味は次のとおりであると主張します。

• 作成、完全/部分更新、または削除を除くすべてのデータ操作

• データ操作ではない操作 (次のような):

• 語句に一致する行を全文検索します。

• 地図上に表示する GIS オブジェクトを生成します。

単語は「しなければならない」という意味です。実装は、記載されているとおりに実行した場合にのみ HTTP に準拠します。 RFC に準拠していないという理由だけで、更新のみに PUT を使用しても明らかに何も問題はありません。データの送受信のすべての詳細を処理するクライアントを提供する場合、どのような動詞が使用されるかは、クライアントのユーザーにとってはあまり重要ではありません。

私は、理由が欲しいタイプです。 RFCに従っていない。 Web アプリほど、REST API において作成と更新を分離することの重要性を私は理解したことがありません。カレンダーの予定、メモ、連絡先などの携帯電話アプリについて考えてみましょう。

• 「作成」はプラス アイコンをクリックすると、空またはデフォルト値の新しいフォームが表示されます。

• 「更新」とは、オブジェクトを選択して鉛筆アイコンを押すことで、現在の値を含む入力フォームが表示されます。

• 入力フォームが表示されると、

では、なぜ REST API と Web フロントエンドが携帯電話アプリと異なる必要があるのでしょうか? 「作成」と「更新」に同じデータ入力フォームを取得できることが電話ユーザーにとって便利であれば、API ユーザーやウェブ ユーザーにとっても同様に便利ではないでしょうか?

PUT を使用することにした場合は、 「作成」または「更新」で SQL をストアとして使用している場合、ほとんどのベンダーは何らかの更新/挿入クエリを備えています。残念ながら、これは 200 OK または 201 Created をいつ返すかを決定するのには役立ちません。 DML クエリの実行時にドライバーが提供する情報を調べて、更新/挿入の挿入と更新を区別する方法を見つけるか、別のクエリ戦略を使用する必要があります。 

簡単な例は、pk 列 = pk 値である更新セットを実行することです。 1 つの行が影響を受けた場合、その行は存在し、更新されています。それ以外の場合、行は存在しないため、挿入が必要になります。 Postgres では、RETURNING 句を利用して、次のように実際に行データだけでなくあらゆるものを返すことができます。

SQL VALUES (...) ON CONFLICT() DO UPDATE SET ( ...) RETURNING (SELECT COUNT() FROMWHERE=) が存在します" data-lang="text/x-sql" style="box-sizing: border-box;">1

INSERT INTO <table>
VALUES (...)
ON CONFLICT(<pk column>) DO
UPDATE SET (...)
RETURNING (SELECT COUNT(<pk column>) FROM <table> WHERE <pk column> = <pk value>) exists

この天才的な点は次のとおりです:

• RETURNING 句の副選択が最初に実行されるため、INSERT ON CONFLICT UPDATE クエリが実行される前に行が存在するかどうかが判断されます。クエリの結果は「exists」という名前の 1 つの列になります。クエリの前に行が存在していた場合は 1 になります。実行され、実行されなかった場合は 0。

• RETURNING 句は、提供されずに生成されたものを含む、行の列を返すこともできます。

挿入または更新が必要かどうかを処理する方法を 1 回だけ判断し、200 OK または 201 Created を処理するすべての PUT で呼び出すことができる単純な抽象化を作成するだけで済みます。

使用する利点の 1 つは、意図した PUT とは、POST が表示されるとすぐに、それが取得または永続化ではないことが確実にわかり、逆に、取得または永続化ではない操作のコードを見つけるには POST を検索する必要があることがわかります。

RFC に記載されているように PUT と POST を使用する利点は、RFC に準拠していない方法でそれらを使用する理由が何であれ、それを上回ると思います。

以上がREST と HTTP セマンティクスの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。