REST API を理解する - せっかちな人のためのガイド

私の記事のクロスポストはこちら

REST (ReプレゼンテーションState Ttransfer) API は、現代の Web 開発のバックボーンです。この記事では、最新の REST API を作成および使用する方法、作成時に考慮すべき設計上の決定事項、および REST の基礎となる理論について詳しく説明します。

実践ガイド

このセクションでは、エンドポイント、メソッド、リクエスト、レスポンスをカバーする HTTP での REST API の使用について詳しく説明します。 API 呼び出しを開始し、プロジェクトに REST を適用するために必要なものがすべて見つかります。

URI を構造化する方法

一般に、URI を扱うには主に 2 つの方法があります。

1. アクションとして
2. リソースとして

次の 2 つの URI について考えてみましょう:

1. https://example.com/getUserData?id=1 (アクション)
2. https://example.com/users/1 (リソース)

どちらの例も、ID が 1 のユーザーのユーザー データを取得することを示しています。違いは、最初の例ではルート /getUserData がアクションを実行しているのに対し、2 番目の例ではルート /users/1 が次の場所であることです。アセットではありますが、どのようなアクションが実行されているかは示されません。このタイプの URI は名詞として機能していると言えます (アクション、つまり動詞ではなく物であるため)。

REST パターンでは、2 番目の例のように URI を厳密に使用することが規定されています。 HTTP メソッドを動詞として使用して、それらの名詞に対してアクションを実行できるように、URI を名詞にしたいと考えています。たとえば、HTTP メソッド GET を使用して /users/1 に関する情報を取得できますが、PUT を使用して対応するユーザーの情報を更新したり、DELETE を使用してユーザーを完全に削除したりできます。

URI について最後に注意すべきことは、上記の例と同様、個々のリソース (この場合は単一のユーザーなど) を参照する場合、URI はそのリソースの一意の識別子で終わる必要があるということです。特定のカテゴリ内のすべてのリソースを参照する場合は、一意の識別子を省略する必要があります。

1. https://example.com/users/1 - ID が 1 の特定のユーザーを参照します
2. https://example.com/users - ID に関係なくすべてのユーザーを参照します

どのようなアクションをサポートするか

REST でサポートする主なアクションは 4 つあり、それらを覚えるために頭字語 CRUD を使用します: Create、Read、U pdate、Delete。これらの各アクションは、そのアクションを実行するために使用できる HTTP メソッドにマップされます。マッピングは次のとおりです:

Action	HTTP Method
Create	POST
Read	GET
Update	PUT / PATCH
Delete	DELETE

サポートするすべてのアクション URI の組み合わせ

すべての REST API は、実際には (少なくとも) 5 ～ 6 個のルートにすぎません。この例では、ベース エンドポイントは /users となり、それを https://example.com でホストするふりをします。

• https://example.com/users を取得します
  • アクション: すべてのユーザー アセットを返します (各アセットは 1 人のユーザーです)
  • リクエスト本文: 空
  • レスポンスボディ: ユーザーアセットのリスト (JSON 配列として)
• GET https://example.com/users/[id] ([id]は変数)
  • アクション: 要求された単一のユーザー アセットのみを返します
  • リクエスト本文: 空
  • レスポンスボディ: 一致する ID (JSON として) を持つユーザー アセットのみ
• POST https://example.com/users
  • アクション: 1 つのユーザー アセットをコレクションに追加します
  • リクエスト本文: 新しいユーザーアセットの作成に必要なすべてのデータ(特定の形式は必要ありません。JSON を推奨します)
  • レスポンスボディ: 一意の ID (JSON として) が挿入された新しく作成されたアセット
• PUT https://example.com/users/[id] ([id]は変数です)
  • アクション: 1 人の既存ユーザーのデータのみを指定されたデータで完全に置き換えます
  • リクエスト本文: 変更されたかどうかに関係なく、既存のユーザーのデータを置き換えるのに必要なすべてのデータ (ID を除く - 特定の形式は必要ありません。JSON を推奨)
  • レスポンスボディ: 一致する ID (JSON として) を持つ新しく更新されたアセット
• (オプション) PATCH https://example.com/users/[id] ([id]は変数です)
  • アクション: 1 人の既存ユーザーのデータのみを指定されたデータで部分的に置き換えます
  • リクエスト本文: 更新が必要なデータのみ (ID を除く - 特定の形式は不要、JSON を推奨)
  • レスポンスボディ: 一致する ID (JSON として) を持つ新しく更新されたアセット
• DELETE https://example.com/users/[id] ([id]は変数です)
  • アクション: ユーザー テーブルから 1 つのレコードだけを削除します
  • リクエスト本文: なし
  • レスポンスボディ: なし (HTTP レスポンスコードのみ) OR 一致する ID (JSON として) で削除されたばかりのアセットからのデータ

設計上の考慮事項

REST パターンを使用するかどうかのエンドポイントの定義以外にも、エンドポイントの構築を始める前に考慮すべきことがたくさんあります。将来的にエンドポイントを更新する可能性はありますか?出力はユーザーに役立つヒントを提供する必要がありますか? REST はあなたの状況で使用するのに適切なパターンですか?これらの質問のいくつかに答えてみましょう。

エンドポイントのバージョン管理

将来の変更が容易になるように、最初から API のバージョン管理について検討し始めることをお勧めします。ユーザーが使用する API バージョンを決定するには、いくつかの方法があります。

• URI のバージョニング
  • バージョン番号は、通常は URL パスのベースに組み込まれます
  • 例:
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• クエリパラメータ
  • バージョン番号は API エンドポイントのクエリ パラメーターとして追加されます
  • 例:
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• ヘッダーベース
  • バージョン番号は特定の一意のヘッダー フィールドです
  • 例 (リクエストヘッダー):
  • x-api-version: 1
  • x-api-version: 2
• コンテンツの交渉
  • バージョンは、表現状態またはメディア タイプに基づいて決定されます。
  • 以下の例では、サーバー コードは、firstName が最初のバージョンのものであり、次のバージョンでは GivenName に変更されたことを認識します。
  • 例 (リクエスト本文):
  • { 名前: 'ヘンリー' }
  • {与えられた名前: 'ヘンリー' }

クイック REST API のモック化

時々、それをいじってみることが、それらがどのように機能するかを学ぶための最良のツールです。 REST をデモするための私のお気に入りのライブラリの 1 つは json-server です。セットアップは非常に簡単です。必要な手順はほんの数ステップだけです。

JSON サーバーをインストールします

npm install json-server

単純なデータ ストアを作成する

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

サーバーを起動します

npx json-server db.json

ローカルサーバーに対して HTTP リクエストを作成します

curl -X GET http://localhost:3000/users/1

簡単な CRUD データ グリッド

完全に機能する REST エンドポイントは、ZingGrid を使用して簡単にデータ グリッドに接続できます。ベース REST URI を に指定するだけです。以下のような要素の src 属性

<zing-grid src="http://localhost:3000/users" editor-controls></zing-grid>

最終的な考え

REST API はウェブ上でさまざまな形やサイズで提供されており、それぞれが特定のニーズを満たすように調整されています。 URI を慎重に構造化し、適切なアクションを選択し、バージョン管理を念頭に置くことで、開発者が楽しく作業できる簡単で柔軟な API を作成できます。これらの基本的な手順を実行すれば、簡単なプロトタイプであっても、時の試練に耐える堅牢で信頼性の高い API に進化させることができます。

以上がREST API を理解する - せっかちな人のためのガイドの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。