API とは？

アプリケーション・プログラム・インターフェイス (API) は、使用するプログラミング言語やプラットフォームに関係なく、異なるソフトウェアシステムが相互に通信できるようにするプロトコルのセットです。API の説明として、「マシンが他のマシンと通信するのをサポートする」という表現が使われることがあります。これは、構造化された一連のルールを通じて通信することで、Web インターフェイスを介さずにプログラムでシステムと対話できるためです。

また API の使用により、新しいソリューションを既存のアプリケーションに統合し、プロセスを自動化することもできます。Web 上には何千もの API が存在し、その多くは無料で使用できます。Postman API Network などの API ディレクトリや、統合するサービスまたは製品の Webサイトを通じて、利用可能な API があるかどうかを確認できます。

API アーキテクチャには、SOAP (Simple Object Access Protocol) API や GraphQL API、RPC (Remote Procedure Call) API など複数の種類がありますが、このガイドでは最も一般的なアーキテクチャのひとつである REST (Representational State Transfer) に焦点を当てます。REST API のスタイルに準拠した Web サービスは、RESTful API と呼ばれます。RESTful API は HTTP を使用し、Web ページの URL とよく似ています。

API の例

恐らく気付かないうちに API の動作を経験しているはずです。お気に入りのレストランの Webサイトで昼食の宅配を注文するところを想像してください。清算時に配達先住所を入力する必要があります。検索バーに住所を入力し始めるとすぐに市や州、郵便番号が自動入力されます。次に支払い情報を入力しようとすると、支払いのフィールドが信頼できるモバイル決済サービスによって処理されることがわかります。最後に注文を完了すると、任意のソーシャル・メディア・プラットフォームを使用してロイヤリティプログラムにサインアップし、注文内容に応じてポイントを稼げます。

住所の自動入力、決済プロセス、ソーシャルメディア経由でのサインアップはどれも API 統合の例です。これらの各コンポーネントをゼロから作成する代わりに、Webサイトは Google Maps API を使用して配達先住所を簡単に収集し、Square API を使用して Square の決済処理システムと統合し、Facebook API を使用して特典アカウントをすばやく作成できます。

REST API の仕組み

REST API は HTTP リクエストとレスポンスを使用して、インターネット経由で情報を交換します。これには、リクエストを行う Web クライアントとリクエストに応答する API サーバーが共通の言語で通信できるというメリットがあります。メッセージリクエストとレスポンスが共通の HTTP Web プロトコルを使用するためです。

REST API には、データの作成 (Create)、読み取り (Read) 、更新 (Update)、削除 (Delete) から成る CRUD と呼ばれる標準的なデータベース機能に沿って一般的なユースケースが多数あります。例えば Facebook API などを使用して新しい特典アカウントを作成するなど、REST API によって作成アクションを実行できます。また、Google Maps API などを使用して住所を取得するなど、データの取得も可能です。 

API リクエストの構造

API リクエストを構成している5つのコンポーネントを見てみましょう。

ベース URL : エンドポイントのプリフィックス。

エンドポイント : リクエストの送信先を示します。

メソッド : 送信されるリクエストの種類を決定します。

ヘッダー : クライアントとサーバーが通信し合うのに役立つ情報を提供します。

本文 : サーバーに送信する情報が含まれます。

基本を理解したところで、さらに詳しく見ていきましょう。

以下は、Google Maps Places API のエンドポイントの例です。

https://maps.googleapis.com/maps/api/place/autocomplete/

このエンドポイントには2つのコンポーネントがあります。ひとつ目は API にデータを提供するドメインを示すベース URL です。この例では、https://maps.googleapis.com がベース URL です。エンドポイントのパスは、リクエストするリソースを決定します。ここでは、Google Maps Places API の Autocomplete という特定のリソースをリクエストしているので、パスは次のようになります : /maps/api/place/autocomplete

なぜこれが URL によく似ているのか疑問に思われるかもしれませんが、理由は実際に URL だからです。ご存知のように、このリクエストは HTTP 経由で実行されています。これをブラウザに入力すると、API に応じてさまざまな形式でフォーマットされたレスポンスを含む非常に基本的な HTML ページが表示されます。JSON は最も一般的なレスポンス形式のひとつです。

しかし、API で実際に何かをするには他のコンポーネントもいくつか必要になります。そのひとつが「メソッド」です。メソッドは、すべてのリクエストに含める必要がある定義済みのキーワードです。最も一般的なメソッドは CRUD の動作に関連する POST (作成)、GET (読み取り)、PUT (更新)、DELETE (削除) です。メソッドは API に実行したい内容を伝え、各エンドポイントは特定のメソッドを期待します。

リクエストヘッダーとは？

API の呼び出しに使用されるもうひとつのコンポーネントがリクエストヘッダーです。リクエストヘッダーは実際には HTTP ヘッダーです。リクエストヘッダーは、リクエストのコンテキストに関する追加情報を提供します。例えば、レスポンスに使用される優先言語をリクエストヘッダーが示す場合があります。ほとんどの API では、クライアントに認証情報を提供する認証ヘッダーも必要とされます。これらは、API を使用するユーザーの正当性を示す個人証明書のようなもので、API のセキュリティの確保に役立ちます。 

メソッドによっては、リクエストの本文で追加データを定義する必要がある場合があります。例えば、POST メソッドを使用して何かを作成する場合、作成中にデータフィールドに入力しなければならないことがあります。

例として、特典アカウントに登録するユーザーのケースを見てみましょう。ユーザーは、Webサイトの特定のフィールドに入力してアカウントを作成します。バックエンドでは API が呼び出され、ユーザーが入力した詳細がリクエストの本文で使用されます。

{
"first_name": "Kris",
"last_name": "Owner",
"email": "krisowner@email.com",
}

API の呼び出し

API リクエストの構成要素を理解したところで、API の呼び出しについて見てみましょう。API を即座にテストしてレスポンスを確認するには、curl または Postman などのアプリケーションを介してリクエストを送信する方法があります。

例えば、特定のユーザーアカウントの詳細を取得したいとします。レスポンスは次のようになります。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "comment": "",
  "created_at": "2020-04-27T19:40:49+00:00",
  "deleted_at": null,
 "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "first_name": "Kris",
  "last_name": "Owner",
  "email": "krisowner@email.com",
}

返されるレスポンスは API と実行したリクエストによって異なります。 

これをさらに細かく見てみましょう。最初の行にはステータスコードが含まれ、この例では成功を意味する「200」が表示されています。次の行の Content-Type ヘッダーは、リクエストした情報の形式を示します。この場合は JSON です。最後にレスポンスの本文にはユーザーの詳細が含まれます。

ここでは、API を呼び出してシンプルなデータ取得を実行する方法をご紹介しました。アプリケーションの Web インターフェース経由でログインすると、恐らく同じ情報を取得できるでしょう。API を呼び出す、より一般的なユースケースは、リクエストをアプリケーションに組み込み、レスポンスで受け取ったデータを使用して何かを実行することです。

API のセキュリティを確保する方法

API の保護はきわめて重要です。機密性の高いデータの安全を維持し、許可されたユーザーのみが API にアクセスできるようにする必要があります。上述の認証ヘッダーに加え、API キーはクライアントを認証し、適切なユーザーのみがアクセスできるようにする一般的な方法のひとつです。また、別の方法として OAuth (Open Authorization) が挙げられます。これは、ログイン資格情報を共有することなく、ユーザーがサードパーティのアプリケーションにリソースへのアクセスを許可できる標準プロトコルです。特定の時間枠内で処理できるリクエスト数のレート制限も、不正アクセスを防ぎ、API のスムーズな運用を維持するうえで重要です。さらに、データ転送時にすべての API 通信の安全を維持し、機密性の高い情報が悪意のある人物の手に渡らないようにするためにも HTTPS 暗号化が欠かせません。

API に関するドキュメントが重要な理由

開発者が Web 開発やアプリケーション開発で API を効果的に使用できるようにするには、明確かつ包括的なドキュメントが必要です。これは、API を最大限に活用する方法を理解するのに役立つロードマップのようなものです。ドキュメントには、エンドポイント、リクエストとレスポンスの形式、認証要件などの重要な情報がすべて網羅されている必要があります。また、使用開始に役立つコードスニペットがいくつか提供されていると、さらに開発者エクスペリエンスを向上できます。加えて、エラー処理やレート制限、API の使用における特定のベストプラクティスや制約に関する情報を含めることもお勧めします。優れた API ドキュメントを提供することで学習曲線を短縮し、開発者が手間をかけずに API をアプリケーションにシームレスに統合できるようになります。

API のバージョン管理

API が成長し進化するにつれて、バージョン管理がプロセスにおいて重要になります。既存の統合に支障をきたすことなく新しい機能の追加や変更を実施できる必要があります。API の URL にバージョン番号を含めることでこれが可能になります (例 : /api/v1/resources)。こうすることで、使用された API のバージョンを明確にできます。もうひとつの方法はリクエストヘッダーでバージョン管理を行う方法で、これによりクライアントが必要なバージョンを指定できます。重要なのは、確かなバージョン管理戦略を導入し、変更あった場合、開発者に確実に伝えることです。重大な変更を導入する場合は、移行プロセスに関するガイドを必ず提供するようにしてください。

API テストが必要な理由

API のテストは完全なヘルスチェックを実施するようなものです。信頼性が高く、パフォーマンスが良好で、必要な仕様に準拠していることを確認する必要があります。API の個々のコンポーネントをテストし、各関数またはメソッドが期待どおりに動作することを確認できるユニットテストは、API テストの最初のステップとして最適です。 

もうひとつの重要なステップとして、API のさまざまな部分がうまく連携して動作し、必要な結果が得られることを保証する統合テストが挙げられます。 

API を徹底的にテストしたい場合は、負荷テストの実行も有効な手段です。負荷テストは、パフォーマンスのボトルネックを見つけ、API が予想されるトラフィック量を処理できることを確認するのに役立ちます。Postman、SoapUI、JMeter など、API テストを容易にし、潜在的な問題を早期に発見するのに役立つ自動テストツールやフレームワークが数多くあります。

API のライフサイクル管理

API をライフサイクル全体にわたって管理することが、長期的な成功と保全性の確保において非常に重要です。API ゲートウェイはナイトクラブの入り口に立つ警備員のような役割を果たします。つまり、すべての API リクエストに対して単一のエントリーポイントを提供し、認証やレート制限、リクエストのルーティングなどの重要なタスクを処理します。 

バージョン管理と非推奨 (API の廃止) に関する戦略も、API のライフサイクルにおいて重要です。API の新しいバージョンを導入する際には、明確な移行計画を提供し、古いバージョンを段階的に廃止する予定時期を開発者に伝えます。また、API を廃止する必要がある場合は、開発者に十分な事前通知を行い、余裕を持って統合を更新できるようにします。少しの計画とコミュニケーションが、API をスムーズに運用し、ユーザーへの大きな混乱を回避するのに大きく役立ちます。

Fastly API の活用方法

Fastly API は、Fastly コンソールを通じて利用できるすべての機能へのアクセスを提供する RESTful API です。

API の使用により、既存のワークフローとの統合や、頻繁に繰り返される面倒なプロセスの自動化など、最も役に立つ形で Fastly サービスやアカウントに関連するオブジェクトを操作できます。例えば、Fastly のリアルタイム分析 API を使用して、Fastly の分析データをカスタム分析ダッシュボードに統合できます。また、自動パージプロセスのセットアップも可能です。想像力 (およびプログラミング技術) 次第で可能性は無限に広がります。

Fastly の API について詳しくは API に関するリファレンスドキュメントをご覧ください。Fastly API は Fastly アカウントで無料でご利用いただけます。