[PHP][API]第 6 章: API 設計

この章は、API の理解における転換点を示します。コンポーネントについて見てきました。次に、概念がどのように結合されて API を形成するかを見ていきます。この章では、API を設計することによって API のコンポーネントを検討します。

データの整理

ナショナル ジオグラフィックは、2011 年にアメリカ人は 80 億枚の写真を撮影すると予測しています。これほど大量の写真があると、人それぞれ異なる方法で写真を整理していることが想像できます。すべてを 1 つのフォルダーに入れることを好む人もいます。年、月、イベントフォルダー階層ごとに整理する人もいます。

API を構築する際、企業は組織的に同様の考えを持っています。第 1 章で述べたように、API の目的は、コンピュータが企業のデータを簡単に操作できるようにすることです。企業は、すべてのデータに単一の URL を使用し、それらを簡単に検索できるようにすることを決定できます (すべての写真を 1 つのフォルダーに入れるなど)。あるいは、各タイプのデータには独自の URL があり、階層的に編成されています (写真にフォルダーやサブフォルダーがあるのと同じです)。各企業は、業界の既存の経験に基づいて、さまざまな形式に応じて API を構築する最適な方法を選択します。

開始するにはフォームを選択してください

API について議論するとき、「一時停止」や「休憩」という用語を聞いて、開発者が実際に開発に取り組んでいるのか、それとも休暇を取る予定なのか疑問に思うかもしれません。実際、これらは Web ベース API の 2 つの一般的なアーキテクチャの名前です。 SOAP (頭字語の略) は、リクエストとレスポンスの標準化された構造を備えた XML ベースの設計です。 Representational Transfer の略である REST は比較的オープン ソースであり、多数のプロトコルを提供していますが、API を設計する際に議論する必要がある領域が多く残されています。

このコースを通じて、私たちは REST API を好むことが主に分かるでしょう。 REST は信じられないほど高速であるため、この優先順位は圧倒的です。これは SOAP が悪いと言っているのではなく、SOAP には利点があります。ただし、REST は最もよく目にする API であるため、ここでは REST に焦点を当てて説明します。残りの部分では、REST API を作成することでコンポーネントについて学習します。

最初のリソース

第 2 章を振り返ると、リソースについて少し話しました。リソースは API 用語 (顧客とピザ) であることを思い出してください。これらは、API を介して世界とやり取りできるようにしたいものです。

企業が API の設計にどのように取り組むかを理解するために、それをピザ パーラーに関連付けてみましょう。

クライアントがピザ屋に連絡できるようにするには、いくつかのことを行う必要があります:

1. どのようなリソースが利用可能かを判断します。
2. これらのリソースに URL を割り当てます。
3. クライアントがこれらのリソースに対して実行する必要があるアクションを決定します。
4. 各ステップでどのようなデータが必要で、どのような形式にする必要があるかを調べます。

資源の確保が最初の難題です。この問題を解決する 1 つの方法は、典型的な対話を段階的に実行することです。ピザ屋の場合は、別のメニューがある場合があります。メニューにはさまざまなピザがあります。お客様が私たちにケーキを作りたいときは、注文する必要があります。この点では、メニュー、ピザ、顧客、注文は素晴らしいリソースのように思えます。まずは注文から始めましょう。

次のステップでは、これらの URL をリソースに割り当てます。可能性はたくさんありますが、幸いなことに、REST 規約はある程度のサポートを提供します。一般的な REST API では、リソースには 2 つの URL が割り当てられます。 1 つ目は、 /orders などのリソース名の複数形です。 2 番目は、リソース名の複数形に単一のリソースを指定する一意の識別子 ( /orders/ など) です。ここで、 はコマンドの一意の識別子です。これら 2 つの URL パターンは、API がサポートする最初のエンドポイントを形成します。これらは、 http://example.com/ のように URL の末尾に配置されるため、単にエンドポイントと呼ばれます。

リソースを選択して URL を割り当てたので、クライアントが実行できるアクションを決定する必要があります。 REST 規約によれば、複数のエンドポイント (/orders) が既存の注文の一覧表示と新しい注文の作成に使用されることがわかります。特定の注文の取得、更新、キャンセルに使用される一意の識別子 ( /orders/ ) を持つエンドポイントがあります。クライアントは、HTTP チャネルを介してリクエストでどのようなアクション (GET、POST、PUT、DELETE) を送信するかをサーバーに伝えます。

API は次のようになります。

| アクション |

| —————— |

| 既存の注文をリストする |

| order/1 | 注文 #1 の詳細を取得 |

| 注文 #2 の詳細を取得 |

| |

| /orders/1 | 注文 #1 をキャンセルします |

注文エンドポイントのアクションを具体化する最後のステップは、クライアントとサーバー間でどのようなデータを交換する必要があるかを決定することです。第 3 章のピザ屋の例を借りると、注文には生地と詰め物のタイプが必要であると言えます。クライアントとサーバー間で情報を転送するためのデータ形式も選択する必要があります。 XML と JSON はどちらも適切な選択肢ですが、読みやすさを考慮して JSON を選択します。

この時点で、機能する API が設計されました。 API を使用してクライアントとサーバーがどのように対話するかを次に示します。

リソースを接続する

私たちのピザ屋の API はシャープに見えます。これまでにないほど注文が入ってきています。実際、ビジネスが非常に好調だったので、顧客ロイヤルティに基づいて注文の追跡を開始することにしました。これを行う簡単な新しい方法は、新しい顧客リソースを追加することです。

注文と同様に、顧客リソースには特定のエンドポイントが必要です。以下で合意されているように、/customers と /customers/ は適切に連携します。詳細は省略しますが、各アクションが各エンドポイントに意味を追加し、そのデータが顧客を表すと仮定しましょう。すべてを完了したと仮定すると、別の興味深い疑問が生じます。注文とユーザー発見をどのように結び付けるかということです。

REST 実践者は、リソース関連の問題を解決する方法に夢中になっています。 /customers/5/orders は 5 番目の顧客の注文を指し、/customers/5/orders/3 は 5 番目の顧客の 3 番目の注文を指します。データ関連の詳細をもっと盛り込むことで物事をシンプルにするべきだと考える人もいます。このモードでは、注文作成の customer_id に注文情報を付けることができます。どちらも REST API で広く使用されているため、知っておく価値があります。

データの検索

システム内のデータが増加するにつれて、エンドポイントがすべてのレコードをリストすることは現実的ではなくなります。私たちのピザ レストランで 300 万件の注文が処理され、トッピングのうちペパロニが何個あるかを知りたい場合を想像してください。 /orders に GET リクエストを送信して 300 万件の注文をすべて受信することは役に立ちません。幸いなことに、REST にはデータを検索するための優れた方法があります。

URL には、まだ言及していないクエリ文字列というコンポーネントがあります。クエリとは、テキストの検索および文字列表現を指します。クエリ文字列は、URL を通じて情報を渡すために URL の末尾に挿入されるテキストです。たとえば、疑問符の後の情報はクエリ データです: http://example.com/orders?key=value。

REST API はクエリ文字列を使用して検索の詳細を定義します。これらの詳細はクエリ パラメーターと呼ばれます。 API は、どのパラメーターを受け取るかを決定し、それらの正確な名前を使用して検索を実装する必要があります。当社のピッツェリア API を使用すると、クライアントは URL: http://example.come/orders?topping=pepperoni を介して注文を検索できます。クライアントは、各パラメータを記号 (「&」) で区切ってリストすることにより、複数のパラメータをクエリできます。例: http://example.com/orders?topping=pepperoni&crust=thin。

クエリ文字列のもう 1 つの用途は、各リクエストで返されるデータの量を制限することです。通常、API は結果をグループ (100 または 500 レコード) に分割し、一度に 1 つのグループを返します。データを分割するプロセスはページング (単語をページに形成する比喩) と呼ばれます。クライアントがすべてのデータをスクロールできるようにするため、API はクエリ パラメーターをサポートし、クライアントが必要なデータのページを固定できるようにします。ピザ ショップ API では、顧客がページとサイズという 2 つのパラメーターを指定できるようにすることで、ページネーションをサポートしています。クライアントが GET/orders?page=2&size=200 のようなリクエストを行った場合、2 ページ目の結果、1 ページあたり 200 件の結果、および 201 ～ 400 件の注文が必要であることは誰もが知っています。

第 6 章の概要

この章では、REST API の設計方法を学びました。私たちは、API によってサポートされる基本的な機能と、コンピューターが簡単に同化できるようにデータを編成する方法を発見しました。

私たちが学んだ重要なポイント:

• SOAP : API アーキテクチャーで標準化されたメッセージ形式。
• REST: リソース センターの API アーキテクチャを制御します。
• リソース : 顧客や注文などの API プロジェクトの名詞。
• エンドポイント: API の一部を形成する URL。 REST では、各リソースに独自のエンドポイントがあります。
• クエリ文字列: データをサーバーに渡すために使用される URL の一部。
• クエリパラメータ: クエリ文字列で見つかった値 (topping=cheese)。
• ページネーション: 構造を管理モジュールに分割するプロセス。