こんにちは。Red Hatでソリューションアーキテクトをしている杉本 拓です。
API基盤の導入を検討されているお客様は多くいらっしゃるかと思いますが、APIを活用していくためには、組織内にどのようなAPIが存在するのか、APIを簡単に発見することができ、そしてそのAPIの仕様がどのようになっているのか、更にどう使うのか、あるいは使用条件など、その詳細情報が見えるようになっている「APIの見える化」が実現されている必要があります。その観点において、APIのデベロッパーポータルというのは非常に重要な役割を持っています。今回の赤帽エンジニアブログでは、Red Hat Application Foundationsに含まれるAPI管理の製品 3scale API Management のデベロッパーポータルをカスタマイズして、APIの見える化を実現する方法について、Red Hat Developersサイトの記事の翻訳を通じて紹介したいと思います。
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について学習をして理解を深め、利用したい場合には登録して利用申請をすることができるようになります。APIを提供する企業は、その目的や想定される利用者に応じてデベロッパーポータルのカスタマイズを行い、デベロッパーポータルの機能を利用して検索やフィルタリングの機能を持ったAPIカタログを簡単に構築することもできるようになります。
以下のセクションでは、Red Hat 3scale API Management を使用して、上記のようなユースケースに対応する動的な API カタログを構築する方法を解説していきます。
APIカタログの構築
では、デベロッパーポータルで表示するすべてのAPIカタログを構築しいきましょう。ここでの実装は、APIs.jsonのプロジェクトをベースとしています。このAPIs.jsonのJSONファイルをデベロッパーポータルで使用することで、APIについて表示するために必要な情報すべてを取得することも可能です。
ただ実際には、さまざまな理由から、3scale API Managementで管理されているすべてのAPIをこのJSONを通じて公開したくない場合もあるかもしれません。そのような場合にはAPI提供者は追加のチェック項目とルールを設定して、どのAPIを公開し、どのAPIを公開しないかを制御することができるようになります。以下の例では、流用制限、価格、サポートなど、APIに関する基本的な情報を持っているAPIである場合のみ公開することとし、それらの基本情報を持っていないAPIは共有の対象外と判断し、発見することができないようにしたいと思います。3scaleでは、APIの基本情報としてアプリケーションプランのフィーチャー (Features)の機能を使用することでこれを実現することができ、関連するフィーチャー (Features)が設定されていないAPIは発見することができないようにすることができます。
注：APIが検索対象となるかどうかのここでの条件はあくまでも例であり、実際の業務観点やユースケースに応じて条件を変更することは当然可能です。例えば、以下ののチェック項目や条件をすべて削除して、3scale API Managementで管理されているすべてのAPIを検出可能にすることも可能です。
APIs.jsonを作成してデベロッパーポータルをカスタマイズするには、以下の手順に従っていきます。
１. 3scale API Managementの管理ポータルにログインし、Audience → Developer Portal → Contentに移動します。New Page のドロップダウンをクリックし、New Sectionを選択して新しいセクションを作成します（図1）。
２. セクションのTitleでcatalogと名前を設定し、図2に示すようにPartial pathを変更します。Create sectionをクリックしてセクションを作成します。カスタマイズに必要なファイルは、このセクションの中で設定していきます。
３. 図3に示すように、以下の表にある設定情報を使用してapis.jsonという新しいページを作成します。Layoutフィールドが空であること、Liquidが有効であること、正しいパスとセクションが設定されていることを確認してください。GitHubのリンクにあるapis.jsonのファイルの中身をソースコードとして貼り付けて、Create Pageをクリックします。
| セクション | 値 |
|---|---|
| Title | apis.json |
| Section | |-catalog |
| Path | /catalog/apis.json |
| Layout | 何も選択されていない状態 |
| Advanced Options > Liquid enabled | チェックを入れてください |
| Code URL | GitHub のリンク |
４. 3scale API Managementの管理ポータルでDeveloper Portal → Draftsに移動し、Publish Allをクリックします。
５. デベロッパーポータルの画面を開き、/catalog/apis.jsonのエンドポイントに移動します。図 5 に示すように、API のリストと関連する詳細が記載された JSON が表示されるはずです。
APIカタログのページ作成
APIカタログのページは、APIを発見するための重要な要素となります。次のステップとして、図6にあるように、すべてのAPIをデベロッパーポータルにリストアップし、それらを検索可能にするためのセクションを追加していきましょう。これにより、API利用者はテキスト検索をおこなってAPIを見つけたり、様々な条件を指定してAPIをフィルタリングしたり、APIを選択してより詳細な情報を取得することができるようになります。このようにして、API利用者は必要なAPIを簡単に見つけることができるようになります。
APIをリストアップするセクションは、以下の手順で作成していきます。
１. 図7に示すように、以下の表にある設定情報を使用してAPI List というタイトルで新しいページを作成します。正しいパスとセクションが設定されていることを確認してください。GitHubのリンクで提供されているコードをコピーして貼り付けて（ここでは、LayoutとLiquidのセクションの設定値を変更する必要はありません）、Create Pageをクリックします。
| セクション | 値 |
|---|---|
| Title | API List |
| Section | |-catalog |
| Path | /catalog/list |
| Code URL | GitHub のリンク |
APIの詳細セクション
一覧ページでAPIを検索して絞り込んだ後、API利用者は選択したAPIについてより詳細を知りたいと思うかもしれません。そのようなニーズに対応するために詳細ページを作っていきましょう。このページには、インタラクティブなAPIドキュメントととして、APIのリクエスト/レスポンスで使用されるデータモデル、サインアップの際のオプション、サブスクリプションのプラン、利用規約、サポートオプションなど、APIを把握するために必要な情報が様々含まれます。
APIの詳細セクションは、以下の手順で作成していきます。
１. 図8に示すように、以下の表にある設定情報を使用してAPI Detailsというタイトルで新しいページを作成します。Liquidが有効であることと、正しいパスとセクションが設定されていることを確認してください。GitHubのリンクにあるコードをコピーして貼り付け、Create Pageをクリックします。Layout セクションは変更する必要はありません。
| セクション | 値 |
|---|---|
| Title | API Details |
| Section | |-catalog |
| Path | /catalog/details |
| Advanced Options > Liquid enabled | チェックを入れてください |
| Code URL | GitHub のリンク |
２. 3scale API Managementの管理ポータルでDeveloper Portal → Drafts へ移動し、Publish All をクリックします（図9）。これにより作成したドキュメントがドラフト状態から公開状態になります。
APIの検索
では最後に、以下の手順でAPIカタログを実際に見てみましょう。
注：3scale API Management 管理ポータルで新しいAPIプロダクトを追加し、アプリケーションプランとそのアプリケーションプランで有効になっているフィーチャー (Features)の設定、およびその API と同じシステム名を持つAPIドキュメントのファイルを使用することによってAPIカタログの動的性質を確認することも可能です。
１. デベロッパーポータルの画面を開き、/catalog/listのエンドポイントに移動するとAPI の一覧が表示され、検索バーと右側の "Categories" の下にあるフィルター（フィーチャー (Features)の設定）を使って検索とフィルタリングができるようになっているはずです (図 10 参照)。
２. APIを選択してクリックすると、API呼び出しのテストをおこなうことができるインタラクティブなドキュメントや、サブスクリプションプランへのサインアップなど、API の詳細情報が表示されます (図 11 参照)。また、API の利用者が API について知りたいと思うことがあれば、さらにセクションや情報を追加することも可能です。また、画像や CSS ファイルなどのアセットの追加も簡単におこなうことができるので、API提供者は、デベロッパーポータル全体を組織のブランドに沿ったものにカスタマイズすることもできます。
まとめ
APIの見える化というのは、どのような組織にとってもAPI戦略の重要な側面であることに間違いありません。APIプロダクトのチームはこのことを後回しにするのではなく、API構築の初期段階から検討していくことでその恩恵に預かることができるようになります。API提供者は、検索、フィルタリング、分類、APIドキュメント、使用に関するルール、利用規約などのAPIの見える化で必要な要素を取り入れることにより、APIのセルフサービス化を効率的に進めていくことができます。
本記事では例を通じて、Red Hat 3scale API Management を使用して動的でインタラクティブな API カタログを作成する方法を学びました。これにより、APIプロダクトのチームは API の見える化と使いやすさを向上させ、API の活用を促進することができます。このようなカスタマイズを3scaleのデベロッパーポータルで行ってみたい方のために、本記事で使用しているファイルはGitHubでアクセスできるようになっていますので是非試してみてください。
Red Hat 3scale API Management を使い始めよう
Red Hat 3scale API Managementを使うことでAPI を簡単に管理できるようになり、パフォーマンス、API利用者の管理、将来の成長のために開発された3scaleのAPI基盤上で、API の共有、保護、配布、制御、収益化を実現することができます。3scale API Management のコンポーネントは、オンプレミス、クラウド、またはその組み合わせのいずれにもデプロイすることができます。
Red Hat OpenShift API Management は、3scale API Management のホスティングかつフルマネージドのバージョンです。興味があり、試してみたいという方は、製品ページをご覧になってみてください。
