API設計とは

API設計には、 APIエンドポイント、リクエストとレスポンスの形式、プロトコル、およびAPIが他のアプリケーションやコンシューマーと通信する方法についての決定が含まれます。API 設計は、 API ガバナンスにおいても重要な役割を果たします。

APIガバナンスとは、組織がAPIを開発、デプロイ、使用する方法を指示する包括的な基準、ポリシー、プラクティスのセットを指します。APIの仕組みを説明した最新の堅牢なドキュメンテーションを使用して、事前に決められたポリシーに準拠したAPIを作成するのが、実効性のあるAPI設計です。これにより再利用性、拡張性、互換性、エンドユーザー・エクスペリエンスを向上させる、適切な設計のAPIが実現します。

APIユースケースやAPI設計には数多くのアプローチがあり、特定のタスクやユースケースにより適したプロトコル、アーキテクチャスタイル、言語が存在します。

Web API の使用が増加するにつれて、一定のプロトコル、スタイル、標準、言語が開発・使用されるようになりました。こうした構造は、受け入れられるデータ型、コマンド、構文などを定義する一連のパラメーター、つまりAPI仕様をユーザーに提供します。実際、これらのAPIプロトコルは標準化された情報交換を容易にします。

一般的なプロトコル、アーキテクチャスタイル、言語としては以下のものがあります。

• SOAP (簡易オブジェクトアクセスプロトコル)
• リモート プロシージャ コール (RPC)
• ウェブソケット
• REST (表現状態転送)
• GraphQL

新しいAPIの適切な構造を選択することは、設計プロセスの重要な一要素です。これらのプロトコル、アーキテクチャスタイル、言語は必ずしも、互いに比較して優れているものや劣っているものがあるというわけではありません。それぞれが異なるタスクに適した、各種のツールであると言えます。

SOAPは、軽量のXMLベースのメッセージング・プロトコル仕様で、エンドポイントがSMTP（簡易メール転送プロトコル）やHTTP（ハイパーテキスト転送プロトコル）などのさまざまな通信プロトコルを通じてデータを送受信できるようにします。SOAPは独立しているため、SOAP APIは異なる環境で動作するアプリケーションやソフトウェア・コンポーネント間、あるいは異なる言語で書かれたアプリやソフトウェア・コンポーネント間で情報を共有することができます。

他の種類のAPIと比較して、SOAP APIはより形式化され構造化された方法で開発される傾向があります。SOAP APIは1990年代から存在しています。これは古く、確立された形式ですが、RESTなどの最新のアーキテクチャーに比べると低速です。

SOAPはデータをXML形式でエンコードすることによって機能するもので、他の形式でのデータ転送はサポートしていません。逆に言えば、SOAP APIはメッセージの転送に必ずしもHTTPを必要としないため、より柔軟にデータの移動が可能です。SOAPは他のプロトコルよりも安全であると考えられており、SOAP APIは機密データを扱うシステムに適しています。

リモート・プロシージャー・コール（RPC）は、オペレーティング・システムで使用される高レベルの通信パラダイムを提供するプロトコルです。RPCは、ネットワークアプリケーションのサポート専用に設計された論理的なクライアント・サーバー間通信システムを実装しています。RPCプロトコルを使用すると、ユーザーはリモート・プロシージャーがローカルであるかのように操作できます。そのため、多くのクライアント・サーバー間通信が必要な状況に適しています。

RPC APIはさらに、XML-RPC、JSON-RPC、gRPCに分類されます。XML-RPCは、特定のXML形式を使用してデータを転送するリモート・プロシージャ・コールです。SOAP APIよりもさらに古いものですが、シンプルで軽量です。JSON-RPCは、JSON（JavaScript Object Notation）を使用してデータを転送するリモート・プロシージャー・コールです。JSONは汎用的なデータ構造を使用しているため、あらゆるプログラミング言語で使用できます。

gRPCは、Googleによって最初に開発された高性能のオープンソースRPCフレームワークです。gRPCはネットワーク・プロトコル HTTP/2 とプロトコル・バッファー・データ形式を使用し、一般にマイクロサービス・アーキテクチャでサービスを接続するために使用されます。

WebSocket APIにより、クライアントとサーバー間の双方向通信が可能になります。このタイプのAPIでは、通信ごとに新しい接続を確立する必要はありません。一度接続が確立されると、継続的な通信が可能になります。このため、Web Socket APIはリアルタイム通信に最適です。

リアルタイムでのチャットや位置追跡、データ・ブロードキャストは、いずれもWebSocket APIに最適なユースケースです。WebSocket APIは、変更が行われるたびに新しい接続を作成する必要がなく、リアルタイムで更新できるため、複数のデバイスやシステムを横断してデータの一貫性と最新の状態を保つデータ同期にも役立ちます。

RESTは、ウェブAPIアーキテクチャの原則のセットです。REST API（RESTful APIとも呼ばれます）は、特定のRESTアーキテクチャの制約を遵守するAPIです。REST APIは、GET、PUT、HEAD、DELETEといったHTTPリクエストを使ってリソースとのインタラクションを行います。RESTはデータをリソースとして利用できるようにし、各リソースは一意のURIで表されます。クライアントはリソースのURIを指定してリクエストします。REST API はステートレスであり、リクエストの合間にクライアントデータを保存することはありません。

RESTful APIは、軽量かつ柔軟で使いやすいことから広く普及しています。プレーン・テキスト、HTML、YAML、XML、JSONなどのさまざまな形式でのメッセージ転送を完全にサポートし、キャッシュもサポートします。そのためさまざまな状況で役立ちますが、一部のステーションでは、タスクを効率的に完了するためにより具体的な言語やプロトコルが必要になります。

GraphQLは、Facebookが2012年に社内で開発したクエリー言語およびAPIランタイムであり、2015年に オープンソース化されました。GraphQLを使用すると、ユーザーは多くのパラメーターを含む複雑なエンドポイントにアクセスすることなく、わずか数行でAPIリクエストを行うことができます。この機能により、APIクエリ、特に複数のリソースを対象とするより複雑な、または具体的なリクエストの生成と応答が容易になります。

Meta社がモバイル・アプリケーションをより効率的にするため開発したクエリ言語だけに、GraphQL APIはもちろんモバイル・アプリケーションに有用です。単一のエントリー・ポイントを提供することで、GraphQL API はサーバーに複数回のリクエストを行うことなく、データをクエリして読み込み時間を短縮できます。

API設計のプロセスには主に以下の4つの段階があります。

• 計画
• 開発
• テスト
• デプロイ

いずれのステップでも、APIに関係する主な利害関係者間の連携が必要です。全員ではなく一部の利害関係者のみが関与した方が良いステップもありますが、API設計ではプロセス全体を通じて共同作業が必要です。そうすることで開発者は、プログラムが必要としない余分な機能を加えることなく、開発プロセス全体をスピードアップすることができます。

どのようなプロジェクトでも、最初のステップは、どのような種類のAPIを開発するのかを全員に周知することです。顧客が電子商取引の環境でインターフェースとして使用することを目的とした公開APIは、認証ワークフローで内部的に使用することを目的としたAPIとは設計と機能のニーズが異なります。開発を始める前に、すべての利害関係者がこれから開発するAPIのユースケースを理解することが重要です。

開発者は、企業が何を開発するのか（また、なぜ開発するのか）を理解することで、使用すべきプロトコルも含め、どのように開発するかという点で正確なアイデアを得ることができます。たとえば、これから開発するAPIでリアルタイム通信が必要であれば、開発時にWebSocketを使用する可能性があることがわかるでしょう。目的に適っているからです。

APIがどうあるべきか、どのように機能するのかについて利害関係者がビジョンを明確にしたら、開発を始めます。API開発のプロセスを通じて、開発者は API エンドポイントの定義、API のデータ・モデルの設計、API がAPIセキュリティーポリシーに準拠していることの確認、エラーの標準ステータス・コードを返すこと、必要に応じて HTTP ヘッダー、 トークン、OAuth、JSON Web トークン (JWT) などの認証メカニズムの実装、エラー・コード、メッセージ、および応答の定義を行います。

開発プロセスのもう一つの側面がドキュメンテーションです。APIの開発中は、すべての選択と決定を、人間に読める文書と機械が判読できるドキュメントに記録しなければなりません。人間が読み取れるドキュメントは、理解しやすい自然言語で書かれたものです。機械で読み取るドキュメントは、OpenAPI仕様などのAPI仕様に準拠している必要があり、形式を標準化することで一貫性を維持し、将来のシステムに統合できるようになります。

APIの設計は、場合によっては反復の多い作業になります。特にAPIが機密データを扱う場合は、バグや欠陥がないか厳密にテストすることが重要です。開発後は、それが意図したとおりに機能するかどうかを確認することが重要です。APIのテストにおいて重要なのはモックアップです。これは、サンプル・データを使用してモック・サーバーを作成し、APIがエンドポイントと正しく通信し、期待される結果を返すかどうかをチェックするプロセスです。

モックアップは API テストと並行して実行できます。APIテストには、リクエストとレスポンスがどのようなものであるかを明確化するコントラクト・テスト、単一のエンドポイントで期待通りのレスポンスが返ってくることを確認するユニットテスト、APIがピーク時のトラフィックの下で実行できるかどうかをテストする負荷テスト、複数のAPIと通信するユーザー・ジャーニーを検証するエンドツーエンド・テストがあります。テストは手動で行うか、または自動テストのフレームワークを実装することもできます。

すべてが意図したとおりに機能していれば、APIをリリースしてデプロイする準備が整ったことになります。この時点までに、他のユーザーとそのマシンがこの API をコンピューター ネットワーク環境に適切に統合できるように、APIドキュメンテーションを完成させることが重要です。APIがリリースされると、利害関係者が予期していなかった問題をユーザーが発見する可能性もあります。開発者が必要と判断した場合に、明確かつ一貫してアプリケーションを更新できるよう、APIのリリース前にバージョニング戦略を策定すると役立ちます。

アプリケーション開発に対するAPIファーストのアプローチでは、ソフトウェア開発プロセスの開始時にAPIの設計を優先し、APIを介して提供されるサービスを使用してアプリケーションを構築します。ソフトウェア開発の早い段階でAPI設計を優先することで、結果としてより再利用しやすく、安全で、効率的で、使いやすく、組織の目標とより合致したAPIが実現する、という考え方です。このアプローチは、コードのロジックを最優先し、開発者が後からソフトウェアに組み込むAPIを作成するコード・ファーストのアプローチとは対照的です。

APIファーストのアプローチでは、API設計が鍵となります。APIファーストでは、APIがアプリケーション開発の中心であり、十分に考え抜かれた設計によって、より高性能で価値の高いアプリケーションの開発を促進します。

強力なAPI設計プラクティスは、開発上および性能上の問題を、より深刻になる前に発見して解決することで、開発者のエクスペリエンスとエンドユーザー・エクスペリエンスの両方を向上させることにもつながります。

利害関係者は、開発プロセスの開始段階から、企業のすべてのアプリが相互にうまく統合され、適切に機能することを確認できます。包括的なドキュメンテーションのあるAPIファーストのアプローチが成功すると、開発者は既存の機能を再作成することなく、既存のAPIを再利用できるようになります。

REST（またはRESTful）APIの構造は緩いものです。唯一の要件は、アーキテクチャー上の制約とも呼ばれる6つのREST設計原則に適合させるということです。この原則には、統一されたインターフェース、クライアントとサーバーの分離、ステートレス、キャッシュ可能性、階層化されたシステム・アーキテクチャー、そしてオプションとしてオンデマンドのコードがあります。

これらのアーキテクチャー上の制約から、RESTful APIはAPIファーストのアプローチに適しています。クライアントとサーバーの分離、およびステートレス性が特に有用です。

RESTful APIでは、クライアント・アプリケーションとサーバー・アプリケーションは互いに独立している必要があります。クライアント・アプリケーションが知っておくべき唯一の情報は、要求されたリソースのUniform Resource Identifier（URI）です。他の方法ではサーバー・アプリケーションとのインタラクションができません。

REST APIはステートレスであるため、それぞれのリクエストには、その処理に必要なすべての情報が含まれていなければなりません。つまり、REST APIはサーバー側のセッションを必要としません。これらの制約から生まれるAPIは企業のサーバーから独立して、より柔軟に機能します。クライアント側とサーバー側のアプリケーションは、API設計に影響を与えることなく、異なる言語やプロトコルを使用して作成できます。

RESTful APIは、スケーラブルで軽量であるため、APIファーストの環境にも適しています。クライアントとサーバーを分離することで、RESTful APIは過去のクライアント要求情報を保持する必要がなく、通信のボトルネックが軽減されるため、拡張性が向上します。効果的なキャッシングによってクライアントとサーバーのインタラクションを減らすことも、拡張性の点でもう1つのメリットとなります。RESTful APIはメッセージ転送にHTTP形式を使用するため、複数の形式でデータ転送を行うことができます。これにより、新しい環境への統合を簡素化できます。

マイクロサービス（マイクロサービス・アーキテクチャー）は、単一のアプリケーションを、疎結合で独立してデプロイできる多数の小さなコンポーネントまたはサービスで構成する、クラウドネイティブのアーキテクチャー形式です。REST APIは、これらの小規模なサービス間の通信を可能にするためによく使われます。

サービスを相互に接続するためにAPIを使用することから、APIファーストのアプローチはマイクロサービス・アーキテクチャーのスキーマに適しています。API設計が組織内で優先され、APIが相互にシームレスに通信するように設計されている場合、開発者はこれらのサービスをより大きなアプリケーションにまとめて、時間を節約できます。

エンタープライズAPIから最大限の価値を引き出すために、組織は多くの場合、以下の要素を重視します。

• APIのガバナンスとドキュメンテーション
• 利害関係者からのフィードバックの収集
• 適切な認証
• バージョン管理
• エラーメッセージの標準化
• 拡張とコンテキスト
• 一貫性

これらの原則は、API設計プロセス全体を通じてすべての利害関係者に情報を提供し、APIを組織の目標や戦略と確実に一致させるのに役立ちます。

APIのガバナンスとドキュメンテーション： 組織全体のAPIガバナンスとドキュメンテーションの戦略を早い段階で確定させることで、一貫性を高め、自社のAPIポートフォリオをより閲覧しやすいものにできます。たとえば、エンタープライズAPIが業界全体の標準に準拠するよう、企業がOpenAPIなどの仕様を採用することが考えられます。いずれにせよ、適切で一貫性のあるガバナンスとドキュメンテーションを維持していれば、新しいAPIのユーザーはAPIとその機能をすぐに理解できるようになります。

利害関係者からのフィードバックの収集： 主要な利害関係者やAPI利用者から早い段階でインプットを得ると、開発プロセス全体を通じて開発者を正しい方向に導き続けるのに役立ちます。コミュニケーションが不十分であれば、API開発に遅れが生じ、APIの価値が損なわれるおそれがあります。

適切な認証とAPIセキュリティー： APIと機密データを保護するために、APIリクエストを検証する認証技術を実装します。APIキー、OAuth、JSON Web トークン（JWT）などの認証メカニズムは、データとAPIトラフィックを保護するさまざまな方法を提供します。クライアントとサーバー間の移動のためにデータをエンコードするプロセスであるAPI暗号化は、データとAPIの保護にも使用されます。

テストとバージョン管理： APIのテストでは、APIのデプロイ前に問題を特定するために、肯定的なケースと否定的なケースの両面にわたるさまざまなシナリオを扱います。APIはテストの過程で進化し、開発者はバグの修正や性能向上を施した新しいバージョンを作成します。新しいAPIバージョンのリリースには、開発者がAPIに主要な機能を追加するなどの他の理由もあります。バージョン管理は、開発者がAPIの変更を管理し、透明性を維持して変更を行い、更新によって現在のユーザーを混乱させないようにするための方法です。

本格的な開発を始める前に、URLベースのバージョニングやヘッダーベースのバージョニングなど、バージョニングの仕組みを定義しておくと役立ちます。

エラーメッセージの標準化： 適切なエラー処理は、問題が発生した場合のトラブルシューティングに役立ち、API利用者のエクスペリエンスを向上させます。エラー・コード、メッセージ、レスポンスは、エラーの性質を正確に説明し、分かりやすく、一貫性を保つものである必要があります。

コンテキストと制約：すべてのAPIは、そのコンテキストに応じて開発方法と機能が決まります。競合プロジェクトの期限、予想されるトラフィック量、および企業がAPIファーストかコードファーストかどうかにより、結果として生まれるAPIが決まります。開発プロセス中に十分な情報に基づいた意思決定を下すことができるよう、すべての利害関係者がこの情報を認識することが重要です。

一貫性： 何よりも、一貫性を保つことが全体としてより良いAPI設計につながります。API設計の一貫性は、単なるバージョン管理やエラー・コードだけではありません。エンドポイントを定義するときは、一貫した命名規則を保つことでエンドポイントの識別が容易になります。APIに特定のリクエストを行うときは、毎回同じ方法で解決する必要があります。APIランドスケープ全体で一貫性が保たれていれば、APIを文書化して将来のユーザーに理解しやすいものにすることも簡単です。