API設計ガイドラインのベストプラクティス

英語によるオリジナルはこちらでご覧いただけます。

多くの大企業は通常、API設計ガイドラインを作成します。その目的は、API開発に携わるすべてのチームにガイドラインの規定を遵守してもらうことです。しかし、ガイドラインの確認、精査、適用を怠る開発者もいることから、規定の遵守という目標が達成されないことはよくあります。

この問題に対処するには、ツールやサービスを作成するための基盤としてAPI設計ガイドラインを捉えることが必要です。開発者がAPI連携のボイラープレートではなくビジネスロジックの開発に意識を向けられるようにする高レベルなツールやサービスを、ガイドラインに基づいて作成します。付加価値を生まない低レベルの作業を自動化できるツールやサービスを、セルフサービスのアーティファクト（成果物）として提供し、開発者の生産性向上につなげる必要があります。

API設計ガイドラインとは

API設計ガイドラインとは、社内のすべてのチームがAPI開発で遵守すべきデザインパターンや設計原則を取りまとめたものです。API設計ガイドラインを策定して導入することは、API戦略のなかでも特に重要な効果をもたらす要素のひとつです。社内全体におけるAPIプラットフォームの構築に、一貫したアプローチを適用しやすくなります。
API設計ガイドラインのドキュメントは、大きく分けて以下の３つの主要なセクションから構成されるべきです。

• 全般的なガイドライン：APIの実装で採用する個々のスタイルに関係なく適用される指針です。
  
• スタイルごとのガイドライン：REST、GraphQL、gRPCなど、個々のスタイルに応じて適用される指針です。
  
• ガバナンスのガイドライン：API設計ガイドラインに関するドキュメント全体の更新方法についての指針です。

全般的なAPI設計のベストプラクティス

このセクションでは、APIの実装スタイルに関係なく、すべてのAPIがライフサイクル全体を通して従うべきルールや推奨事項について記述します。このセクションの内容に関しては、以下の原則をお勧めします。

• APIファースト：ステークホルダーと密接に協力して、APIコントラクトを設計するところから始める必要があります。長期の使用に耐えうる安定したAPIを構築するためには、適切なコントラクトを作成しておくことが決定的に重要です。
  
• クライアントに支障をきたさない：どのスタイルのAPIを採用した場合でも、修正を加えるときには下位互換性を堅持し、破壊的変更を避ける必要があります。
  
• セキュリティバイデザイン：すべてのAPIに求めるセキュリティ要件を明確にしておきます。ここでは、認証、認可、アクセス制御、HTTPヘッダー、セッション管理、検証、CORS（クロスオリジンリソース共有）、TLS暗号化、証明書管理、ペネトレーションテストなどのトピックをカバーします。この分野の対象トピックについては、OWASP API Security Projectが非常に参考になります。

APIスタイルごとのベストプラクティス

このセクションでは、APIのスタイルごとの指針について規定します。（最も広く使われているスタイルはRESTful API）すべてのスタイルで取り上げるべきトピックとして、特に該当しそうなガイドラインは、次の通りです。

• API仕様：APIコントラクトを記述する際に使用するAPI仕様のフォーマットは、すべてのコントラクトで共通化しておく必要があります。使用するフォーマットはこのセクションで規定します。例えば、OpenAPI、AsyncAPIなどがあります。
  
• APIOps：プラットフォームで成果を上げるための任務の一環として、APIOpsパイプラインの特定の手順で使用するツールについて、指針を定めておくとよいでしょう。例えば、CI／CDのツールチェーン、Gitリポジトリの構成、テスト用フレームワークなどです。
  
• プロトコル管理：HTTPとHTTPSのどちらを使うかの基準や、URIの定義方法、プロトコルのメソッド、ステータスコード、ヘッダーなどのメタデータの使用方法について規定します。
  
• メッセージ形式：APIで使用できるメッセージ形式は多くあります。テキスト形式ではXML、JSON、YAMLなどが特に一般的ですが、そのほかにバイナリ形式や、問題の報告で使うような特別な形式もあります。社内で使用するメッセージに関して、どの場合にどのメッセージ形式を使用するかを規定します。
  
• データ型：日付と時刻、言語コード、国コード、通貨など、標準的なデータ型の表現方法を明確に規定しておく必要があります。
  
• 共通処理：重要な役割を持つAPIのほとんどが提供する機能として、ページ分割、検索、実行時間の長いタスク、バッチ処理、パラメータ数が多いクエリーリクエスト、ローカライズ、レート制限などがあります。こうした機能はすべてのAPIで一貫性を持たせておくことが重要です。レスポンスのキャッシュやハイレベルなパフォーマンス最適化の機能も、共通処理の一貫性に直接関係します。
  
• 改良（バージョニング）：下位互換性を損なわずに変更を扱う方法は不可欠です。なお、この点は「クライアントに支障をきたさない」の原則でも指摘済みです。このセクションでは、URIの設計方法、命名規則、旧バージョンから新バージョンへの変更や移行に対処する方法を規定します。

APIの設計とガバナンスのベストプラクティス

API設計ガイドラインは生きたドキュメントであり、ガイドラインの影響が及ぶすべてのステークホルダーのフィードバックをもとにして、改良と充実を図っていく必要があります。
企業は一般に、フィードバックを集めてガイドラインを適切に改良するための組織を設置します。こうした組織は、APIギルド（API Guild）と呼ぶ場合や、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のなかで対処する方法については、標準化する項目を増やすほど、実装段階でのセキュリティ標準の適用や実行時の監査に対する検証が容易になります。認証、認可、レート制限、TLSの適用、クエリーパラメータ管理、メッセージ形式についての規定を、セキュリティ関連のAPI設計ガイドラインとして明確に定めておくと、OWASP API Security Top 10に挙がっている多くの脅威に対して効果があります。

エンタープライズアーキテクチャ：すべてのAPIが設計ガイドラインを遵守

API戦略にはガバナンスが欠かせません。組織のAPI設計ガイドラインについての議論や改良を促すうえで、API実践コミュニティを設立することは有益です。API設計ガイドラインの作成と改良が全員参加型のプロセスになり、すべてのステークホルダーからの支持と関与が得られやすくなります。また、API設計ガイドラインに基づいて作成するアーティファクトやサービスの担当を決めるうえでもプラスになります。

API設計ガイドラインの対象読者となるステークホルダー

API設計ガイドラインのドキュメントを社内の全員に強制的に読ませ、すべてのAPIがそのガイドラインに従うよう義務づけるのは、おそらく最善の策ではありません。必要なのは、開発者への強制ではなく支援です。APIの開発が正しいステップを経て進むためには、それが最も簡単な方法でなくてはなりません。APIガイドラインは、全員が確認・精査すべきドキュメントというだけの存在にはとどまらず、APIコミュニティが付加価値の高い作業に専念できるようにするためのアーティファクトの作成指針という役割も担っています。
アーティファクトにはさまざまな形態があります。その一部について紹介します。

ソフトウェア開発キット（SDK）

API設計ガイドラインで規定する要素の多くは、APIクライアントに向けて提供するSDKという形で具体化できます。SDKは高レベルなユースケースに対応し、クライアントからの呼び出しを、ガイドラインで定められた適切なメッセージ形式、データ型、共通処理に変換します。
つまり、目的のユースケースに応じたインターフェースを利用することでクライアントが素早く価値を得られるとともに、その際の低レベルでのやり取りがAPI設計ガイドラインに準拠したものとなります。

テンプレートとサンプルコード

APIクライアントとAPIプロデューサの生産性を高めるには、ガイドラインに準拠したテンプレートやサンプルコードを提供することも効果的です。テンプレートとは例えば、各種プログラミング言語のソースコードや、OpenAPI仕様の一部などです。ガイドラインを現実のシナリオに適用する方法を明確に伝えるには、優れた具体例が一番です。さらに一歩進んで、主要な開発環境向けに、IDEの拡張機能を作成してもよいでしょう。このなかでは、APIの開発にスムーズに着手するためのプロジェクトテンプレートや部分的なコードを提供します。

ゴールデンイメージとハードニング

APIマネジメントにおいてセキュリティを確実に遵守する方法のひとつに、ゴールデンイメージの作成があります。APIゲートウェイインフラやAPI実装に関して、セキュリティとハードニングのガイドラインに準拠したゴールデンイメージを作成し、アーティファクトのリポジトリに格納して、APIチームに配布すれば、APIライフサイクル全体を通してセキュリティのガイドラインを確実に適用できます。

IDおよびアクセス管理

すべてのAPIコールにIDおよびアクセス管理を確実に適用することも、セキュリティを遵守するうえで欠かせない要素のひとつです。API環境で利用するIDプロバイダのソリューションに関して、採用や導入の条件をAPIガイドラインで規定しておく必要があります。APIゲートウェイでは、該当する認証と認可のプラグインをあらかじめ設定しておいて、ゴールデンイメージとして配布できます。

静的解析とAPIOps

APIガイドラインの規定のうち、プロトコル管理、メッセージ形式、データ型の規定については、Spectralなどで用いられる形式の静的解析ルールに基づいて、APIOpsパイプラインで検証できます。
APIガイドラインでは、デプロイするAPIがガイドラインに準拠していることを検証するためのルールを規定する必要があります。しかし、APIOpsのパイプライン全体のうちで、静的解析はステップのひとつに過ぎません。パイプライン設定を定義済みのGitリポジトリテンプレートを用意して、後でその設定にカスタマイズや拡張を加えられるようにしておくと、APIチームにとって非常に便利になります。パイプラインの構成について、その構成を採用した理由や、チームが正しく利用する方法を、API設計ガイドラインに記述しておく必要があります。

まとめ

API設計ガイドラインはAPI戦略の中心的な要素のひとつです。企業のAPIコミュニティは、この記事で示したようなAPIの原則とパターンに基づいて、一貫性のあるAPIプラットフォーム開発を社内全体で推進するための一連のツールやサービスを開発できます。適切なガバナンスの仕組みのもとで、すべてのステークホルダーが、自分もガイドラインの策定と改良に関与する一員であるという思いや、自ら取り組んでいく決意を抱くはずです。

社内のAPIとマイクロサービスを管理しましょう。Kongの統合プラットフォームをぜひお試しください。
製品のお問い合わせやデモのご依頼はこちらから