APIの検出にAPI開発者ポータルが必要な理由

企業は、ビジネスライン全体でアプリケーションとデータを接続したり、パートナーとの統合を実現して、カスタマーエクスペリエンスを向上するため、ますますAPIへの依存度を高めています。TechRadarによると、今日の平均的な企業では合計15,564のAPIを利用しており、前年比で201%増となっています。

APIの数が増え続けるにつれて、APIポートフォリオの管理はますます複雑になります。どのAPIが利用可能でどこにあるのか、などを検出・追跡し、その使用方法に関するドキュメントを見つけるのも至難の業になっています。APIは、総合的なAPI戦略がなければ、プラットフォーム運用チームの管理能力をはるかに超えるスピードで増殖します。私たちはこの問題をAPIスプロールと呼び、以前の記事でも、なぜそれが重大な脅威であるのかについて説明しました。この記事では、NGINXを使ってAPI開発者ポータルをセットアップし、APIのスプロールを防ぐ方法について詳しく説明します。

＞APIとは？定義やできること、セキュリティ対策まで解説

APIインベントリの構築

結局のところ、APIは利用されてこそ意味あるものです。つまり、APIコンシューマは API を見つける方法を必要としています。適切なシステムが整っていないと、APIスプロール現象により開発者は自分のアプリケーションに必要なAPIを見つけることが難しくなります。APIのリストはさまざまな事業部門ごとに保管され、知識はエンジニアの非公式なネットワークを通じてチーム間で共有されるだけです。

APIスプロール化を防ぐ最初の手順の1つは、APIのシングルソースオブトゥルース（信頼できる唯一の情報源）を作成することです。このプロセスは、APIのインベントリを作成することから始まります。しかし、正確なインベントリ構築は課題といえます。新しいAPIが導入され、古いAPIが廃止される中、ターゲットは常に変化します。また、環境全体で「シャドウAPI」を見つける必要があります。これらは、時間の経過とともに忘れられてしまったAPI、不適切に廃止されたAPI、または標準プロセス外で構築されたAPIなどです。

管理されていないAPIは、一見無害に見えて重大な問題を引き起こすAPIスプロールの最たる兆候であり、明らかなセキュリティへの悪影響と隠れたコスト負担を招きます。利用可能なAPIの正確なインベントリがない場合、APIチームはドキュメントを探すのに時間を費やさなければならず、さまざまなチームが同様の機能を構築するという、無駄な重複作業が発生するリスクも高くなります。また、特定のAPIに変更を加えると、適切なバージョン管理が行われないと、コストが発生するやり直しや停止につながる可能性があります。

APIの自動検出といった手法は、管理されていないAPIの兆候を特定し、対処するのに役立ちます。ただし、問題解決のためには、根本的な原因（壊れたプロセスと所有権の欠如など）を排除する必要があります。実際には、APIインベントリとドキュメントをCI/CDパイプラインに統合することが長期的にAPIポートフォリオ全体の可視化を確保する唯一のアプローチです。こうすることで、オンラインになったすべてのAPIを手動で追跡しなくても例外を特定して修正するだけで済みます。

API開発者ポータルによるAPI検出の合理化

API開発者ポータルが役立つ分野の1つにAPI検出の合理化があります。このポータルは、APIコンシューマがAPIをアプリケーションに統合する前に、APIを検出し、ドキュメントを読み、APIを試すための中心的な場所です。また、これは所有権と連絡先情報が記載されたメインAPIカタログとしても機能するため、さまざまなサービスのAPIを維持する管理者を誰もが知ることができます。

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

• API検出の合理化 – APIをアクセス可能な場所に公開することで、開発者はAPIを簡単に見つけて、プロジェクトに使用できます
• 明確で最新のドキュメントの提供 – 開発者は、常にAPIの機能に関する最新のドキュメントにアクセスできます
• 適切なバージョン管理の確保 – バージョン管理をサポートすることで、ダウンストリームアプリケーションを機能停止させずに、APIの新しいバージョンを導入できます
• APIクレデンシャルの生成 – オンボーディングプロセスを合理化することで、開発者はサインインし、APIアクセスに使用するクレデンシャルを生成できます
• APIの試用 – 開発者はプロジェクトにAPIを統合する前に、ポータルでAPIを試すことができます

API戦略の一環として、API開発者ポータルのメンテナンス方法を理解する必要があります。APIチームの作業を増やすことなく、APIの公開、バージョン管理、文書化をシームレスに統合・自動化するロータッチなアプローチが必要です。

NGINXによる信頼できる唯一の情報源の作成

シームレスなAPI検出を実現化するために、開発者は、APIを検出し、その使い方を理解し、プロジェクトに組み込むことができる唯一の情報源を作成する必要があります。つまり、開発者ポータルと最新のドキュメントが必要となるのです。

F5 NGINX Management Suiteの一部であるAPI Connectivity Managerを使用すると、APIの公開、バージョン管理、文書化を開発ワークフローに直接統合することができます。そのため、API開発者ポータルは常に最新の状態に保たれます。API Connectivity Managerは、APIやドキュメントをホストするためのAPI開発者ポータルを簡単に作成できるほか、カスタムページを追加したり、ブランディングに合わせて開発者ポータルを完全にカスタマイズしたりできます。

API Connectivity Managerが特定のユースケースに対処するのにどのように役立つかを見てみましょう。開発者ポータルクラスタの設定と公開に関する詳細な手順については、API Connectivity Managerのドキュメントを参照してください。

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

多くの場合、APIコンシューマがドキュメントに期待する品質や詳細のレベルと、多忙なAPI開発者が限られた時間とリソースで現実的に提供できるものとの間には、大きな隔たりがあります。多くの自社開発のドキュメントツールは、開発ライフサイクルや他のエンジニアリングシステムとの統合に失敗しています。ただし、これは必ずしもそうだと言うわけではありません。

NGINXがどのように役立つか：API Connectivity Managerは、OpenAPI仕様を使用してAPIゲートウェイにAPIを公開し、開発者ポータルに付随するドキュメントを自動的に生成します。そうすることで、API開発者は時間が節約でき、APIコンシューマは常に必要なものを見つけることができます。OpenAPI仕様ファイルは、API Connectivity Managerのユーザーインターフェイスを介して直接アップロードするか、REST API経由でコールを送信することでアップロード可能です。これにより、CI/CDパイプラインによる文書化プロセスの自動化が簡単になります。

API Connectivity Managerでドキュメントを公開するには、左側ナビゲーション列の「Services（サービス）」をクリックして「Services（サービス）」タブを開きます。ワークスペースの名前をクリックするか、新しいワークスペースを作成します。

ワークスペースに移動したら、ワークスペースの名前と説明が記載されているボックスの下にある「API Docs（APIドキュメント）」をクリックします（スクリーンショットの example-api）。「 Add API Doc （API Docの追加）」ボタンをクリックするだけで、OpenAPI仕様ファイルをアップロードできます。 「 Save （保存）」ボタンをクリックすると、ドキュメントは開発者ポータルに公開されます。

適切なバージョン管理の確保

バージョン変更は、常に慎重を期して行う必要があります。これは、多くのサービスが単一のAPIとインタラクトする可能性があるマイクロサービス環境では、特にそうです。新しいバージョンの導入や古いバージョンの廃止の際には、慎重なアプローチがないと、たった1つのブレークダウンが何十ものマイクロサービスにわたって連鎖的な停止を引き起こす可能性があります。

NGINXがどのように役立つか：API Connectivity ManagerでOpenAPI仕様ファイルを使用すると、APIのバージョン管理が簡単になります。バージョン番号の設定に加えて、各バージョンのドキュメントを提供し、そのステータス（最新、アクティブ、廃止、または非推奨）を管理できます。

APIの新しいバージョンを公開するには、左側ナビゲーション列の「Services（サービス）」をクリックします。表のワークスペース名をクリックし、表示されたページで環境名をクリックします。その後、「 + Add Proxy （+ プロキシの追加）」ボタンをクリックします。 ここから、OpenAPI仕様をアップロードし、ベースパスとバージョンを設定してURI(たとえば、/api/v2/)を作成し、その他の重要なメタデータを入力します。「 Publish （公開）」ボタンをクリックして、APIプロキシを保存して公開します。

APIの元のバージョンは、新しいバージョンと一緒に引き続き使用することが可能です。これにより、ユーザは余裕を持って、アプリケーションやサービスを徐々に最新バージョンに移行できます。準備が整い次第、元のバージョンのAPIを完全に非推奨にします。図2は、公開されて運用中の Sentence Generator APIの2つのバージョンを示しています。

APIクレデンシャルの生成

APIの採用を促進するには、APIコンシューマのためにオンボーディングプロセスを可能な限りシンプルにする必要があります。ユーザがAPIを検出したら、開発者ポータルに安全にサインインしてクレデンシャルを生成する方法が必要なのです。これらのクレデンシャルはAPIの機能へのアクセスを許可します。ほとんどの場合、ユーザは自分でサインアップできるように、セルフマネージドワークフローを実装したいと考えています。

NGINXがどのように役立つか：API Connectivity Managerは、開発者ポータルでセルフマネージドAPIワークフローをサポートするため、ユーザはAPIにアクセスための独自のリソースクレデンシャルを生成できます。リソースクレデンシャルは、APIキーまたはHTTP Basic認証を使用してポータルで管理します。また、開発者ポータルでシングルサインオン（SSO）を有効にしてアクセスを保護し、認証されたAPIコンシューマがリソースクレデンシャルを管理できるできるようにすることも可能です。

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

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

「Developer Portal Clusters（開発者ポータルクラスタ）」セクションで、作業中の開発者ポータルの「Actions（アクション）」列の「…」アイコンをクリックし、ドロップダウンメニューから「Edit Advanced Config（詳細設定の編集）」を選択します。図5では、単一のDeveloper Portalクラスタは、devportal-clusterです。

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

開発者ポータルでのAPIの試行

API戦略の成功を判断する方法の1つは、「最初の API 呼び出しまでの時間」メトリックを追跡することです。これにより、開発者がAPIで基本的なリクエストを送信するのにかかる時間が明らかになります。

APIの最初のエントリポイントとして、明確で簡潔なドキュメントが不可欠です。このドキュメントにより、ユーザはAPIの操作方法について基本的に理解することができます。通常、開発者はAPIリクエストをテストする前に、新しいコードを作成しAPIをアプリケーションに統合する必要があります。開発者ポータルで実際のデータを使用してAPIと直接インタラクトする方法を提供することで、開発者はより迅速にテストを開始できるようになります。アプリケーション用のコードを1行も書かなくても、効果的に最初のAPIを呼び出すことができるのです!

NGINXがどのように役立つか：API Connectivity Manager開発者ポータルでSSOを有効にすると、APIコンシューマはAPI Explorerを使って、ドキュメントページでAPI呼び出しを試すことができます。API Explorerを使用して、APIのエンドポイント、パラメータ、レスポンス、データモデルを調査し、ブラウザでAPI呼び出しを直接テストできます。

図7は、動作中のAPIエクスプローラを示しています。このケースでは、Sentence Generator APIを試しています。ユーザは適切なクレデンシャルを選択し、リクエストを作成し、APIから実際のデータを含むレスポンスを受け取ります。

概要

APIは組織にとって極めて重要です。APIを管理・保護するための最初のステップは、どこにあるにせよすべてのAPIのインベントリを作成することから始まります。しかし、API検出はソリューションの一部にすぎません。APIスプロールの根本的原因に対処するには、開発およびエンジニアリングのライフサイクルにAPIインベントリ、ドキュメント、バージョン管理を組み込むことがとても重要です。

NGINX Management Suiteの30日間無料トライアルをお試しください。このトライアルには、API Connectivity Manager、APIゲートウェイとしてのNGINX Plus、そしてAPIを保護するためのNGINX App Protectへのアクセスが提供されています。