APIディスカバリにAPI開発者ポータルが必要な理由

NGINX | 2022年12月06日

企業では、事業部門をまたいでアプリケーションとデータを接続し、パートナーと連携して顧客体験を提供するために、APIへの依存がますます高まっています。TechRadarによると、現在、平均的な企業が利用するAPIは合計15,564個に上り、前年比で201%増加しています。

APIの数が増え続けるにつれて、APIポートフォリオの管理は複雑さを増します。利用可能なAPIとその所在を把握して追跡することや、使用方法に関するドキュメントを見つけることが難しくなります。包括的なAPI戦略がなければ、Platform Opsチームの管理能力を上回る速さでAPIが増殖する可能性があります。F5では、この問題を「APIスプロール」と呼んでいます。以前の記事では、これが重大な脅威となる理由を説明しました。この記事では、NGINXを活用してAPI開発者ポータルを構築し、APIスプロールに対処する方法を詳しく解説します。

APIインベントリの作成

結局のところ、APIは利用されて初めて役に立ちます。つまり、API利用者が必要なAPIを見つけられる仕組みが必要です。適切なシステムが整備されていないと、APIが無秩序に増え、開発者がアプリケーションに必要なAPIを見つけることが難しくなります。良くても、事業部門ごとにAPIの一覧を管理し、エンジニア同士の非公式なネットワークを通じてチーム間で情報を共有している程度です。

APIスプロールへの対策に向けた最初のステップの1つは、APIに関する信頼できる唯一の情報源を構築することです。そのためには、まずAPIのインベントリを作成します。ただし、新しいAPIが導入され、古いAPIが廃止されるたびに状況が変化するため、正確なインベントリを維持するのは容易ではありません。また、時間の経過とともに忘れられたAPI、適切に廃止されなかったAPI、標準プロセス外で構築されたAPIなど、環境全体に存在する「シャドーAPI」も特定する必要があります。

管理されていないAPIは、APIスプロールがもたらす最も深刻な問題の1つであり、明らかなセキュリティ上の懸念だけでなく、見えにくいコストも伴います。利用可能なAPIの正確なインベントリがなければ、APIチームはドキュメントの探索に時間を費やさなければなりません。また、複数のチームが類似した機能を構築することで、無駄な作業の重複が生じる大きなリスクがあります。さらに、適切なバージョン管理がなければ、特定のAPIへの変更によって、コストのかかる手戻りが連鎖的に発生したり、サービス停止に至ったりする可能性もあります。

APIの自動検出などの手法は、管理されていないAPIという症状の特定と対処に役立ちます。しかし、問題を解決するには、機能していないプロセスと責任の所在の欠如という根本原因を取り除く必要があります。実際、APIのインベントリとドキュメントをCI/CDパイプラインに統合することが、APIポートフォリオ全体の可視性を長期的に確保する唯一の方法です。新たに稼働するAPIを1つずつ手動で追跡する必要はなく、例外のみを特定して修正すれば済みます。

API開発者ポータルでAPIディスカバリを効率化

API開発者ポータルは、APIの検出を効率化するうえで役立ちます。API利用者は一元化された場所でAPIを見つけ、ドキュメントを確認し、アプリケーションに統合する前にAPIを試すことができます。また、API開発者ポータルは、所有者と連絡先の情報を備えた一元的なAPIカタログとしても機能するため、各サービスのAPI保守を誰が担当しているかを全員が把握できます。

F5のAPIリファレンスアーキテクチャ<.htmla>の中核コンポーネントである効果的なAPI開発者ポータルは、主に次のユースケースを実現します。

API戦略の一環として、API開発者ポータルの保守方法を検討する必要があります。APIチームの作業を増やすことなく、APIの公開、バージョン管理、ドキュメント作成をシームレスに統合できる、自動化された運用負荷の低いアプローチが必要です。

NGINXでAPIの信頼できる唯一の情報源を構築

APIをシームレスに検出できるようにするには、開発者がAPIを見つけ、使用方法を学び、自身のプロジェクトに導入できる、信頼できる唯一の情報源を構築する必要があります。そのためには、開発者ポータルと最新のドキュメントが必要です。

API Connectivity ManagerはF5 NGINX Management Suiteの一部であり、APIの公開、バージョン管理、ドキュメント作成を開発ワークフローに直接統合できるため、API開発者ポータルを常に最新の状態に保つのに役立ちます。APIとドキュメントをホストするAPI開発者ポータルを簡単に作成できるだけでなく、カスタムページを追加し、ブランドに合わせて開発者ポータルを全面的にカスタマイズできます。

API Connectivity Managerが特定のユースケースへの対応にどのように役立つかを見ていきましょう。詳細な手順については、API Connectivity Managerのドキュメントで「開発者ポータルクラスターのセットアップ」および「開発者ポータルの公開」を参照してください。

APIドキュメントを自動生成

API利用者がドキュメントに期待する品質や詳細さと、多忙なAPI開発者が限られた時間とリソースで現実的に提供できる内容との間には、多くの場合、大きな隔たりがあります。自社開発のドキュメント作成ツールの多くは、開発ライフサイクルや他のエンジニアリングシステムと連携できていません。しかし、こうした状況は変えられます。

NGINXによる支援： API Connectivity Managerは、OpenAPI Specificationを使用してAPIをAPIゲートウェイに公開し、付随するドキュメントを開発者ポータルに自動生成します。これにより、API開発者の時間を節約し、API利用者が必要な情報をいつでも見つけられるようにします。OpenAPI Specificationファイルは、API Connectivity Managerのユーザーインターフェースから直接アップロードするか、REST API経由で呼び出しを送信してアップロードできます。そのため、CI/CDパイプラインを通じてドキュメント作成プロセスを容易に自動化できます。

API Connectivity Managerでドキュメントを公開するには、左側のナビゲーション列で［Services］をクリックして［Services］タブを開きます。Workspaceの名前をクリックするか、［新規作成］をクリックします。

Workspaceを開いたら、Workspaceの名前と説明が表示されているボックス（スクリーンショットではexample-api）の下にある［API Docs］をクリックします。［Add API Doc］ボタンをクリックして、OpenAPI Specificationファイルをアップロードします。［Save］ボタンをクリックすると、ドキュメントが開発者ポータルに公開されます。

図1：OpenAPI SpecificationファイルをAPI Connectivity Managerにアップロードしてドキュメントを作成

適切なバージョン管理の徹底

バージョン変更は常に慎重に扱う必要があります。特に、多数のサービスが単一のAPIと連携する可能性があるマイクロサービス環境では、細心の注意が求められます。新しいバージョンの導入と古いバージョンの廃止を慎重に進めなければ、1つの破壊的変更が原因で、数十のマイクロサービスに連鎖的な障害が発生する可能性があります。

NGINXによる支援：OpenAPI SpecificationファイルをAPI Connectivity Managerと組み合わせて使用することで、APIのバージョンを容易に管理できます。バージョン番号の設定に加え、各バージョンのドキュメントを提供し、そのステータス（最新、アクティブ、廃止、非推奨）を管理できます。

APIの新しいバージョンを公開するには、左側のナビゲーション列で［Services］をクリックします。表でWorkspace名をクリックし、開いたページでEnvironment名をクリックします。次に、［+ Add Proxy］ボタンをクリックします。ここでは、OpenAPI Specificationをアップロードし、ベースパスとバージョンを設定してURI（例：/api/v2/）を作成し、その他の重要なメタデータを入力できます。［Publish］ボタンをクリックして、APIプロキシを保存して公開します。

APIの元のバージョンは、新しいバージョンと並行して引き続き利用できます。これにより、ユーザーはアプリケーションやサービスを最新バージョンへ段階的に移行する時間を確保できます。準備が整ったら、APIの元のバージョンを完全に廃止できます。図2は、公開され本番環境で稼働しているSentence Generator APIの2つのバージョンを示しています。

図2：API Connectivity Manager内でのアクティブなAPIバージョンの管理

API認証情報の生成

APIの利用を促進するには、API利用者のオンボーディングプロセスをできる限り簡素化する必要があります。ユーザーがAPIを見つけた後は、開発者ポータルに安全にサインインし、認証情報を生成できる仕組みが必要です。この認証情報により、APIの機能にアクセスできるようになります。多くの場合、ユーザーが自分でサインアップできるセルフサービス型のワークフローを実装することが望まれます。

NGINXによる支援：API Connectivity Managerは、デベロッパーポータルでセルフマネージド型のAPIワークフローをサポートし、ユーザーがAPIへのアクセスに使用するリソース認証情報を自ら生成できるようにします。リソース認証情報は、ポータル上でAPIキーまたはHTTP Basic認証を使用して管理できます。また、デベロッパーポータルでシングルサインオン（SSO）を有効にすることで、アクセスを保護し、認証済みのAPI利用者がリソース認証情報を管理できるようにすることも可能です。

開発者ポータルでSSOをすばやく有効にするには、左側のナビゲーション列で［Infrastructure］をクリックします。表でWorkspaceの名前をクリックします（図3では「team-sentence」）。

図3：［Infrastructure］タブのWorkspace一覧

［Workspace］ページの表で、設定するEnvironmentの名前をクリックします（図4では「prod」）。

図4：Workspace内のEnvironmentの一覧

［Developer Portal Clusters］セクションで、作業対象のデベロッパーポータルの［…］列にあるActionsアイコンをクリックし、ドロップダウンメニューから［Edit Advanced Config］を選択します。図5では、Developer Portal Clusterはdevportal-clusterの1つだけです。

図5：Developer Portal Clusterの［Edit Advanced Config］オプションの選択

次に、左側のナビゲーション列で［Global Policies］をクリックします。OpenID Connect Relying Partyポリシーの行にある［…］アイコンを［Actions］列でクリックし、ドロップダウンメニューから［Edit Policy］を選択してポリシーを設定します。詳細については、「API Connectivity Managerドキュメント」を参照してください。

図6：シングルサインオンを有効にするためのOpenID Connect Relaying Partyグローバルポリシーの設定

Developer PortalでAPIを試す

API戦略の成果を測定する方法の1つとして、「初回API呼び出しまでの時間」という指標を追跡できます。この指標から、開発者がAPIを使用して基本的なリクエストを送信するまでにかかる時間がわかります。

明確で簡潔なドキュメントは、ユーザーがAPIの基本的な使い方を理解する最初の入り口として不可欠です。通常、開発者がAPIリクエストをテストするには、まずAPIをアプリケーションに統合するための新しいコードを記述する必要があります。デベロッパーポータル上で実際のデータを使用してAPIを直接操作できるようにすれば、開発者はアプリケーションのコードを1行も記述せずに最初のAPI呼び出しを実行でき、はるかに迅速に作業を開始できます。

NGINXによる支援： API Connectivity Managerの開発者ポータルでSSOを有効にすると、API利用者はAPI Explorerを使用して、ドキュメントページ上でAPI呼び出しを試すことができます。API Explorerでは、APIのエンドポイント、パラメーター、レスポンス、データモデルを確認し、ブラウザーから直接API呼び出しをテストできます。

図7は、API Explorerの実際の使用例として、Sentence Generator APIを試す様子を示しています。ユーザーが適切な認証情報を選択してリクエストを作成すると、APIから実際のデータを含むレスポンスを受信します。

図7：開発者ポータルでのAPIのテスト

まとめ

APIは組織にとって不可欠です。APIのガバナンスとセキュリティ確保に向けた第一歩は、場所を問わず、すべてのAPIを棚卸しすることです。しかし、APIディスカバリは解決策の一部にすぎません。APIの無秩序な増加という根本原因に対処するには、APIの棚卸し、ドキュメント化、バージョン管理を開発およびエンジニアリングのライフサイクルに組み込む必要があります。

NGINX Management Suiteの30日間無料トライアルを開始すると、API Connectivity Manager、APIゲートウェイとしてのNGINX Plus、およびAPIを保護するためのNGINX App Protectをご利用いただけます。