APIs 101: API 設計を巡って必要になるあらゆる知識

※この投稿は米国時間 2020 年 10 月 22 日に、Google Cloud blog に投稿されたものの抄訳です。

アプリケーション プログラミング インターフェース（API）は、ソフトウェア間でやり取りできるようにする仕組みです。基盤となるシステムの複雑さを抽象化することで、それらが相互運用を目的としていない場合でも、斬新な方法でシステムを接続できます。したがって、最新のデジタル エクスペリエンスと今日の特にエキサイティングな多くのビジネス チャンスの実行という両面で、API は重要な要素となっています。

ただし、API がもたらす価値には、API がアクセスを提供する機能とデータだけでなく、API の設計方法も関連します。多くの API は統合用に設計されています。つまり、システムを接続しても、API の将来的な使用は予測しない、1 回限りのプロジェクトとして設計されています。特に有用性の高い API は、開発者の仕事を容易にするよう設計される傾向があります。つまり、API は、将来他の開発者が使用することを見越して設計されるのが一般的です。これは消費用の設計です。

この特質は、ビジネスの効率と革新能力に大きな影響を与える可能性があります。消費用に設計された API により、重要な機能とデータが再利用可能になり、デベロッパーはさまざまな API をモジュール式に組み合わせて、新しいデジタル エクスペリエンスを作成したり、新しい戦略を実現したりできます。パートナー エンゲージメントの合理化やデジタル エコシステムへの参加促進などの目標においては、この方法で API を活用できることが重要です。

これとは対照的に、統合用に設計された API は、直近のプロジェクトのニーズには対応しても、デベロッパーが今後 API を使用するうえではあまり役立ちません。これらの API は、将来のデベロッパーが容易に理解できるようには設計されておらず、その期待どおりには動作しない可能性があります。これにより、新しい API の作成が必要になり、古い API が最初からより広い視野で設計されていれば回避できたはずの作業と遅延が発生する可能性があります。

API 設計者は、どのようにすれば価値とデベロッパーの生産性を最大化する API を確実に構築できるでしょうか。Google Cloud ブログで何度もこの話題を取り上げてきましたが、今回の投稿では、特に有用な API 設計のヒントとベスト プラクティスをいくつかご紹介します。

さまざまなアプローチ: REST、RPC、GraphQL

API には、システムの相互作用に対するさまざまなアプローチや、さまざまな設計基準が含まれる可能性があるため、各種 API 設計モデルを概説するのが出発点としては最適です。詳しくは、API 設計: gRPC、OpenAPI、REST の概要と、それらを使用するタイミングを理解する、REST 対 RPC: API で解決しようとしている問題とは、GraphQL: API コンシューマのための一貫したアプローチの構築、ウェブ API をエンティティ指向にする理由をご覧ください。

全体的な API 設計の概要

多くの API 設計トピックの詳細な概要については、電子書籍のウェブ API 設計: ミッシング リンク: デベロッパー好みのインターフェースを設計するためのベスト プラクティスが強力な基盤を提供します。2014 年以来 Google 内部で使われており、Google が Cloud APIs と他の Google API を設計する際に従う Google Cloud API 設計ガイドも同様にご参照ください。また、API 設計に関する広範な Q&A をまとめた API 設計のベスト プラクティスと主な注意点も併せてご覧いただくことをおすすめします。

具体的な課題とベスト プラクティス

上記の記事では、多くの幅広いトピックを扱う一方で、API の長期的な価値に影響を与える可能性のある、より詳細で具体的な API 設計の多くの課題についても探索しました。

たとえば、API では多くの点で関係を定義することが重要になります。小売業者の API では、情報モデルは、顧客、注文、カタログ アイテム、カートなどのエンティティ間の関係に対処します。同様に、金融 API は、口座がどの顧客に属しているか、または各クレジットもしくはデビットがどの口座に適用されるかを表します。API デベロッパーが関係を表現する最も一般的な方法は、公開するエンティティのフィールドでデータベース キー、またはそのプロキシを公開することです。ただし、少なくともウェブ API の場合、このアプローチには、代替手段であるウェブリンクに対していくつかの欠点があります。その理由については、API 設計: API で関係を表すためにキーではなくリンクを使用すべき理由をご覧ください。

同様に、API URL を作成する際に、人間が読みやすい名前を中心に構築された URL を使用するタイミングと、静的な数値識別子に依存する URL を使用するタイミングを区別することは簡単ではありませんが重要ではあります。たとえば、銀行口座では、数値識別子が使用されていないと確実に参照するのが難しい場合があります。口座所有者に関する詳細情報はすべて変更されやすく（名前、住所、婚姻状況など）、またはあいまいになりがちです（生年月日と出生地）。もしくはその両方に当てはまる場合もあります。所有者の信頼できる識別子があったとしても、口座の所有権が変更される可能性があります。静的な数値識別子は最も信頼できる選択です。より深く掘り下げるには、API 設計: URL には名前と識別子のどちらを使うべきかをご覧ください。API 設計における人間にとっての読みやすさとシステムの安定性のトレードオフに関する具体的な議論については、ウェブ API における URL デザインの誤った二分法をお読みください。

消費用に設計された API は、基本的に開発者向けのソフトウェア製品であるため、他のソフトウェア製品と同様に反復して改善できます。ただし、新しい API のバージョニングの処理には微妙な違いが伴う場合があるので、API 設計: どのバージョンのバージョニングが適している？と API のバージョニングに関する一般的な誤解を必ず参照してください。

最後に、API は、検索エンジンによるシングルページ アプリケーションのインデックス作成方法に影響を与える可能性があります。そのため、これがビジネスのニーズに関連していると思われる場合は、API 設計と SEO に関する 2 部構成シリーズをご覧ください。

API をさらに活用する

これで、より強力かつユーザー フレンドリーな、汎用性の高い API を作成する準備が整いました。これらの消費に重点を置いた API の目的の一つは再利用を容易にすることであり、より充実したアプリケーションをより迅速に構築するための、無数の新しい方法を実現できるようになります。API がどのようにビジネス上の成果を促進しているかについてさらに詳しく学習するには、Google Cloud Next ‘20: OnAir の API 関連トピックのまとめをご確認ください。API 構築にぜひご活用ください。

-Chris Latimer