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

企業は、ビジネスライン全体でapplicationsとデータを接続し、パートナーと統合し、顧客エクスペリエンスを提供するために、ますます API に依存するようになっています。 TechRadarによると、現在、平均的な企業は合計 15,564 個の API を活用しており、前年比201% 増加しています。

API の数が増え続けるにつれて、API ポートフォリオの管理の複雑さが増します。 利用可能な API とその場所を発見して追跡したり、その使用方法に関するドキュメントを見つけたりすることが難しくなります。 総合的な API 戦略を導入しないと、プラットフォーム運用チームが管理できるよりも速く API が増殖する可能性があります。 私たちはこの問題をAPI スプロールと呼んでおり、前回の投稿でそれがなぜ重大な脅威なのかを説明しました。 この記事では、NGINX の助けを借りて API 開発者ポータルを設定することで、API の無秩序な増加に対処する方法について詳しく説明します。

APIのインベントリを作成する

結局のところ、API は使用されるまで役に立ちません。つまり、API の消費者には API を見つける方法が必要です。 適切なシステムが導入されていないと、API が乱立し、開発者がapplicationsに必要な API を見つけることが困難になります。 せいぜい、API のリストはさまざまな事業部門によって保持され、エンジニアの非公式ネットワークを通じてチーム間で知識が共有されます。

API の無秩序な増加と戦うための最初のステップの 1 つは、API の信頼できる唯一のソースを作成することです。 このプロセスは、API のインベントリを構築することから始まります。 ただし、正確なインベントリは課題です。新しい API が導入され、古い API が廃止されるため、常に変化する目標です。 また、環境全体にわたって「シャドー API」を見つける必要があります。シャドー API とは、時間の経過とともに忘れ去られた API、不適切に廃止された API、または標準プロセスの外で構築された API のことです。

管理されていない API は、明らかなセキュリティへの影響と隠れたコストの両方を伴う、API の拡散の最も陰険な症状の 1 つです。 利用可能な API の正確なインベントリがなければ、API チームはドキュメントを探すのに時間を費やす必要があります。 さまざまなチームが同様の機能を構築するため、無駄な重複作業が発生する重大なリスクがあります。 また、適切なバージョン管理を行わないと、特定の API を変更すると、コストのかかる一連のやり直しや、停止につながる可能性もあります。

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

API 開発者ポータルで API の検出を効率化

API 検出の合理化は、API 開発者ポータルが役立つ領域の 1 つです。 これは、API コンシューマーが API を発見し、ドキュメントを読み、applicationsに統合する前に API を試すための中心的な場所を提供します。 API 開発者ポータルは、所有権と連絡先情報を備えた中央 API カタログとしても機能するため、さまざまなサービスの API の保守の責任者が誰であるかを全員が把握できます。

当社のAPI リファレンス アーキテクチャ<.htmla>のコア コンポーネントである効果的な API 開発者ポータルにより、いくつかの重要なユース ケースが可能になります。

• API の検出を効率化– API をアクセスしやすい場所に公開することで、開発者がプロジェクト内で API を簡単に見つけて使用できるようになります。
• 明確で最新のドキュメントを提供する– 開発者がAPIの機能に関する最新のドキュメントに常にアクセスできるようにします。
• 適切なバージョン管理の確保– バージョン管理のサポートにより、下流のapplicationsを停止させることなく、API の新しいバージョンを導入できます。
• API 認証情報の生成–オンボーディング プロセスを合理化して、開発者がサインインし、API アクセスに使用する認証情報を生成できるようにします。
• API を試す– 開発者がプロジェクトに統合する前に、ポータルで API を試すことができる

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

NGINX で API の唯一の真実のソースを作成する

シームレスな API 検出を可能にするには、開発者が API を見つけ、その使用方法を学習し、プロジェクトにオンボードできる単一の信頼できるソースを作成する必要があります。 つまり、開発者ポータルと最新のドキュメントが必要になります。

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

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 でドキュメントを公開するには、左側のナビゲーション列の[サービス]をクリックして [サービス]タブを開きます。 ワークスペースの名前をクリックするか、新しいワークスペースを作成します。

ワークスペースに入ったら、ワークスペースの名前と説明が表示されているボックスの下にある「API ドキュメント」をクリックします (スクリーンショットではexample-api )。 OpenAPI 仕様ファイルをアップロードするには、 「API ドキュメントの追加」ボタンをクリックするだけです。 [保存]ボタンをクリックして、ドキュメントを開発者ポータルに公開します。

適切なバージョン管理を確実にする

バージョンの変更は常に慎重に処理する必要があります。これは、多くのサービスが単一の API とやり取りする可能性があるマイクロサービス環境では特に当てはまります。新しいバージョンの導入と古いバージョンの廃止に慎重なアプローチを取らないと、1 つの重大な変更によって数十のマイクロサービスに連鎖的な障害が発生する可能性があります。

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

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

API の元のバージョンは、新しいバージョンと並行して引き続き利用できます。 これにより、ユーザーはapplicationsやサービスを最新バージョンに段階的に移行できるようになります。 準備ができたら、API の元のバージョンを完全に廃止できます。図 2 は、公開済みおよび実稼働中の Sentence Generator API の 2 つのバージョンを示しています。

API認証情報を生成する

API の採用を促進するには、API 利用者にとってオンボーディング プロセスをできるだけシンプルにする必要があります。 ユーザーが API を見つけたら、開発者ポータルに安全にサインインして資格情報を生成する方法が必要になります。 これらの認証情報により、API の機能にアクセスできるようになります。ほとんどの場合、ユーザーが自分でサインアップできるように、自己管理型のワークフローを実装する必要があります。

NGINX がどのように役立つか: API Connectivity Manager は開発者ポータルで自己管理型 API ワークフローをサポートしているため、ユーザーは API にアクセスするための独自のリソース資格情報を生成できます。 リソース資格情報は、 API キーまたはHTTP 基本認証を使用してポータルで管理できます。 また、開発者ポータルでシングル サインオン (SSO) を有効にして、アクセスを保護し、認証された API コンシューマーがリソース資格情報を管理できるようにすることもできます。

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

ワークスペース ページのテーブルで、構成する環境の名前をクリックします (図 4 では、 prodです)。

開発者ポータル クラスターセクションで、作業中の開発者ポータルのアクション列にある…アイコンをクリックし、ドロップダウン メニューから[詳細設定の編集]を選択します。 図 5 では、単一の開発者ポータル クラスターはdevportal-clusterです。

次に、左側のナビゲーション列で「グローバル ポリシー」をクリックします。 OpenID Connect 証明書利用者ポリシーを構成するには、その行の [アクション] 列にある…アイコンをクリックし、ドロップダウン メニューから[ポリシーの編集]を選択します。 詳細については、 API 接続マネージャーのドキュメントを参照してください。

開発者ポータルでAPIを試す

API 戦略の成功を測定する方法の 1 つは、「最初の API 呼び出しまでの時間」メトリックを追跡することです。このメトリックは、開発者が API を使用して基本的なリクエストを送信するのにかかる時間を示します。

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

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

図 7 は、API Explorer の動作を示しています。この場合は、Sentence Generator API を試しています。ユーザーは適切な資格情報を選択し、リクエストを作成し、API から実際のデータを含む応答を受け取ります。

まとめ

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

NGINX Management Suite の30 日間無料トライアルを開始します。これには、 API Connectivity Manager 、API ゲートウェイとしてのNGINX Plus 、および API を保護するNGINX App Protectへのアクセスが含まれます。