REST の概要。パート 2: クライアントとサーバー間の通信

REST の概要。パート 1: REST とは何ですか? このパートでは、クライアントとサーバーの間で通信がどのように行われるかについて詳しく説明します。その過程で、新しい用語を見つけて説明していきます。 すべてを明確にするために、例として RESTful アプリケーションを使用してクライアントとサーバーの通信を分析します。顧客とその注文に関する情報を保存する Web アプリケーションを開発しているとします。言い換えれば、私たちのシステムは特定のエンティティに対して操作を実行できます。つまり、エンティティの作成、編集、削除、およびエンティティに関する情報の表示が可能です。これらのエンティティは次のようになります。

• 顧客（顧客）
• 注文（顧客からの注文）
• アイテム（商品）

RESTful アーキテクチャでは、クライアントはデータを取得または変更するためにサーバーにリクエストを送信し、サーバーはそのリクエストに対する応答をクライアントに送信します。

リクエスト

クライアント要求は、ほとんどの場合、HTTP プロトコルを使用して行われます。一般に、HTTP リクエストはいくつかのコンポーネントで構成されます。

• HTTPメソッド
• ヘッダ
• URI
• リクエストボディ

以下では、各コンポーネントについて詳しく説明します。

URIとリソース

クライアントがリクエストを通じて受信または変更するデータはリソースと呼ばれます。クライアントとサーバーの通信は、リソースの操作がすべてです。REST では、リソースとは名前を付けることができるものすべてです。ある意味、これらは Java のクラスに似ています。Java では、あらゆるもののクラスを作成できます。したがって、REST では、リソースはユーザー、ドキュメント、レポート、注文など何でもあります。これは、何らかのエンティティの抽象化、または画像、ビデオ、アニメーション、PDF ファイルなどの特定のもののいずれかになります。この例では、3 つのリソースがあります。

• 顧客（顧客）
• 注文（顧客からの注文）
• アイテム（商品）

クライアントは、エンドポイントと呼ばれるリソースの場所にリクエストを送信します。簡単に言えば、エンドポイントはネットワーク上のアドレスのようなものです。さらに深く掘り下げると、エンドポイントはURIであると言えます。、つまり、抽象的または物理的なリソースを識別する一連の文字です。URI (Uniform Resource Identifier) エンドポイントまたは URI は、リソースへのパスを意味するパスと呼ばれることもあります。この記事では、URI という用語を使用します。特定のリソースにはそれぞれ一意の URI が必要です。サーバー開発者は、各リソースが常に独自の URI を持つようにする責任があります。この例では、私たちは開発者なので、知っている方法でそれを行います。リレーショナル データベースの主キーとして数値識別子を割り当てるのが一般的であるのと同様に、REST でも各リソースには独自の ID があります。REST のリソース ID は、多くの場合、リソースに関する情報を保存するデータベース内のレコードの ID と一致します。REST URI は通常、何らかのリソースを説明する名詞の複数形で始まります。例えば、 "

• /customers — 利用可能なすべての顧客の URI
• /customers/23 — 特定の顧客、つまり ID=23 の顧客の URI
• /customers/4 — 特定の顧客、つまり ID=4 の顧客の URI。

しかし、それだけではありません。注文を追加することで URI を拡張できます。

• /customers/4/orders — 顧客番号 4 によるすべての注文の URI
• /customers/1/orders/12 — 顧客 No. 1 が作成した注文 No. 12 の URI。

さらに製品を追加して拡張を続けると、次の結果が得られます。

• /customers/1/orders/12/items — 顧客 No. 1 が作成した注文 No. 12 の全製品リストの URI。

ネストのレベルを追加するときに重要なのは、URI を直感的にすることです。

HTTPメソッド

HTTP メソッドは任意の文字 (制御文字と区切り文字を除く) のシーケンスであり、リソースに対して実行される主な操作を示します。一般的な HTTP メソッドがいくつかあります。RESTful サービスで最も頻繁に使用されるものをリストします。

• GET — 特定のリソース (ID を介して) またはリソースのコレクションに関する情報を取得します。
• POST — 新しいリソースを作成する
• PUT — リソースを変更します (ID を使用)
• DELETE — リソースを (ID を使用して) 削除します。

ヘッダー

リクエストとレスポンスには HTTP ヘッダーが含まれます。これらは、リクエスト (またはレスポンス) に関する追加情報を伝えます。ヘッダーはキーと値のペアです。最も一般的なヘッダーのリストはWikipediaでご覧いただけます。REST に関しては、クライアントは多くの場合、リクエストの「Accept」ヘッダーをサーバーに送信します。このヘッダーは、クライアントがどのような形式で応答を受け取ることを期待しているかをサーバーに伝えるために必要です。さまざまな形式が MIME タイプのリストに示されています。 MIME (MultiPurpose Internet Mail Extensions) は、インターネット上で送信できるように情報をエンコードし、メッセージをフォーマットするための仕様です。各 MIME タイプは、スラッシュで区切られた 2 つの部分 (タイプとサブタイプ) で構成されます。さまざまな種類のファイルの MIME タイプの例:

• テキスト — テキスト/プレーン、テキスト/CSS、テキスト/html
• 画像 — 画像/png、画像/jpeg、画像/gif
• オーディオ - オーディオ/wav、オーディオ/mpeg
• ビデオ — ビデオ/mp4、ビデオ/ogg
• アプリケーション — application/json、application/pdf、application/xml、application/octet-stream

たとえば、リクエストには次のようなヘッダーを含めることができます。

Accept:application/json

このヘッダーは、クライアントが JSON 形式で応答を受信することを期待していることをサーバーに伝えます。

リクエストボディ

これはクライアントからサーバーに送信されるメッセージです。リクエストにボディがあるかどうかは、HTTP リクエストの種類によって異なります。たとえば、GET リクエストと DELETE リクエストには通常、リクエスト本文が含まれません。ただし、PUT リクエストと POST リクエストは可能です。それはリクエストの目的によって異なります。結局のところ、ID (URL で渡される) を使用してデータを受信したり削除したりするために、追加のデータをサーバーに送信する必要はありません。ただし、(POST リクエストを通じて) 新しいリソースを作成するには、リソースを送信する必要があります。既存のリソースを変更する場合も同様です。REST では、ほとんどの場合、リクエスト本文は XML または JSON 形式で送信されます。JSON 形式が最も一般的です。新しいリソースを作成するためにサーバーにリクエストを送信するとします。忘れていない場合は、顧客の注文を管理するアプリケーションの例を検討しました。新しい顧客を作成したいとします。当社の場合、次の顧客情報を保存します: 名前、電子メール、電話番号。この場合、リクエストの本文は次の JSON になる可能性があります。

{
  "name" : "Amigo",
  "email" : "amigo@jr.com",
  "phone" : "+1 (222) 333-4444"
}

リクエストをまとめる

そこで、クライアントのリクエストに含まれる可能性のあるものを調査しました。リクエストの例を説明とともにいくつか紹介します。

反応

サーバーの応答について少しお話しましょう。通常、応答は次の部分で構成されます。

• 応答コード
• ヘッダー
• レスポンスボディ

一般に、応答ヘッダーは要求ヘッダーとそれほど変わりません。さらに、一部のヘッダーは応答と要求の両方で使用されます。リクエストボディに関してもすべてが明確であると思います。多くの場合、本文はクライアントから要求された情報を返します。GET リクエストに応じて返される情報は JSON 形式である場合もあります。しかし、最後の部分はもう少し興味深いです。

HTTPレスポンスコード

HTTP 応答コードについてさらに詳しく考えてみましょう。HTTPステータス コードは、 HTTP プロトコル経由で行われたリクエストに対するサーバー応答の最初の行の一部です。10 進数 3 桁で構成される整数です。最初の桁は、応答ステータス コードのクラスを示します。通常、応答コードの後に​​はスペースで区切られた英語の説明フレーズが続きます。このフレーズは、人間が判読できる応答の理由です。例:

• 201 件が作成されました
• 401 不正
• 507 ストレージが不十分です

応答コードはクライアントにリクエストの結果を伝え、次にどのようなアクションを実行するかをクライアントが決定できるようにします。応答コードは、いくつかのクラスまたはグループに分類されます。

• 1XX — 情報提供
• 2XX — これらのコードは、クライアントのリクエストが正常に受信され、処理されたことを示します。
• 3XX — これらのコードは、操作を正常に完了するには、通常は別の URI に対して追加のリクエストを行う必要があることをクライアントに通知します。
• 4XX — クライアント エラー。このようなコードは、リクエストが正しく構成されていないことが原因で発生する可能性があります。もう 1 つの例は、よく知られた「404 Not Found」コードです。これは、クライアントが存在しないリソースを要求したときに発生する可能性があります。
• 5XX — サーバーエラー。サーバーが操作の失敗の原因である場合、これらのコードはクライアントに返されます。

REST の概要。パート 3: Spring Boot での RESTful サービスの構築