API の公開（オリジナル バージョン）

ここでは、API をポータルに公開してアプリ デベロッパーが API を利用できるようにする方法について説明します。

API 公開の概要

API をポータルに公開するプロセスは次の 2 つの手順に従います。

1. ポータルに公開する API プロダクトを選択します。
2. 公開する API がどのようなものであるかをアプリ デベロッパーが理解できるようにするため、OpenAPI 仕様のスナップショットから API リファレンス ドキュメントを自動生成します（スナップショットの詳細については、OpenAPI 仕様のスナップショットとはをご覧ください）。

API をポータルに公開すると、ポータルが自動的に次のように更新されます。

• API リファレンス ページがポータルに追加される
  API リファレンス ページには、OpenAPI 仕様のスナップショットから自動生成された API ドキュメントが表示されます。デベロッパーはこの API ドキュメントを読み、[Try It] をクリックして API リクエストを発行し、出力を確認できます。

  注: このページの内容を直接編集することはできません。このページはポータルのページのリストには表示されません。

  

• API リファレンス ドキュメントへのリンクが API ページに追加される
  API ページ（これはサンプル ポータルに含まれています）には、ポータルに公開されたすべての API の一覧があり、各 API にはその詳細を説明する API リファレンス ドキュメントへのリンクが設定されています。

  注: このページの内容を直接編集することはできません。このページはポータルのページのリストには表示されません。

  

OpenAPI 仕様のスナップショットとは

それぞれの OpenAPI 仕様は、API のライフサイクル全体を通して信頼できる情報源として使用されます。開発から公開、さらにモニタリングに至るまで、API ライフサイクルのすべてのフェーズで同じ仕様が使われます。仕様を変更する際は、その変更が他のライフサイクル フェーズを通して API にどのような影響を与えるかを認識する必要があります。詳細については、仕様を変更するとどうなるかをご覧ください。

API を公開するとき、API リファレンス ドキュメントの基となる OpenAPI 仕様のスナップショットをとります。このスナップショットは、仕様ストア内の特定のバージョンの仕様を表します。仕様エディタを使用して OpenAPI 仕様を変更する場合、最新の変更を API リファレンス ドキュメントに反映するために、その仕様の別のスナップショットをとることができます。

CORS のサポートを API プロキシに追加する

API を公開する前に、CORS のサポートを API プロキシに追加してクライアント側のクロスオリジン リクエストを可能にする必要があります。

CORS（クロスオリジン リソース シェアリング）は、ウェブページで実行される JavaScript XMLHttpRequest（XHR）呼び出しがオリジン以外のドメインのリソースとやり取りできるようにする標準メカニズムです。CORS は、すべてのブラウザに組み込まれている同一オリジン ポリシーに対する一般的な解決策です。たとえば、ブラウザで実行されている JavaScript コードから Twitter API への XHR 呼び出しは失敗します。その理由は、ブラウザに該当ページをサービスしているドメインが、Twitter API をサービスしているドメインと同じでないからです。CORS はこの問題を解消すべく、サーバーがクロスオリジンでリソースを共有したい場合に、サーバーが「オプトイン」できる（承諾を得られる）ようにします。

API を公開する前に CORS のサポートを API プロキシに追加する方法については、API プロキシへの CORS サポートの追加をご覧ください。

注: 最近のブラウザはほとんどが CORS に対応しています。サポートされているブラウザの一覧については、こちらをご覧ください。CORS の詳細な説明については、クロスオリジン リソース シェアリングの W3C 勧告をご覧ください。

APIs ページにアクセスする

[APIs] ページにアクセスするには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。

または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。

API のリストが表示されます。

上の図に示すように、[APIs] ページでは次のことができます。

• ポータルで使用可能な API の詳細を見る
• API をポータルに追加する
• API リファレンス ドキュメントを更新するため、API プロダクトに関連付けられた OpenAPI 仕様のスナップショットをとる
• ポータル上の API を公開または公開停止する
• ポータル上の API のオーディエンスを管理する
• 関連付けられた仕様を編集する（仕様エディタを使って仕様を作成するを参照）
• ポータルから API を削除する
• 「孤立した」API（対応する API プロダクトが Edge から削除された API）を一目で見分け、API プロダクトを再作成するか、API をポータルから削除する

API をポータルに追加する

注: 最大 100 個の API をポータルに追加できます。

API をポータルに追加するには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。
   または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。
3. [+ API] をクリックします。
   [Add API Product to Portal] ダイアログが表示されます。

4. ダイアログの [API Product] タブで、ポータルに追加する API プロダクトを選択します。
   

5. [次へ] をクリックします。

6. スナップショットに使用するソースを選択します。
   API プロダクトに含まれる API プロキシをすでに OpenAPI 仕様から作成した場合は、その仕様をプルダウン リストから選択します。
   

   あるいは、次の項目を選択することもできます。

   • [No spec] を選択し、API を公開した後に仕様のスナップショットをとるに従って仕様を追加します。
   • [Choose a different spec] を選択して新しい仕様を選択またはアップロードします。

7. API をポータルに公開するには、[Published] チェックボックスをオンにします。まだ API を公開する準備ができていない場合、[Published] はオフにします。
   この設定は後でポータル上の API を公開または公開停止するに従って変更できます。

8. API のオーディエンスを管理するため、[Audience] で次のいずれかを選択してアクセスを許可します。

   • Anonymous users: すべてのユーザーにページの閲覧を許可します。
   • Registered users: 登録ユーザーのみにページの閲覧を許可します。

   この設定は後でポータル上の API のオーディエンスを管理するに従って変更できます。

9. [Finish] をクリックします。

仕様のスナップショットをとる

API を公開した後、いつでも OpenAPI 仕様の新しいスナップショットをとって、ポータルで公開された API リファレンス ドキュメントを更新できます。

OpenAPI 仕様のスナップショットをとるには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。
   または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。
3. スナップショットをとる API にカーソルを合わせて、操作メニューを表示します。

4. をクリックします。

   注: 現在のスナップショットが、選択されているソース仕様に対して最新である場合は、メッセージが表示されます。

5. [Snapshot Source] プルダウンから既存の仕様を選択するか、[Choose a different spec] を選択して API のドキュメントの生成に使用する新しい仕様を選択またはアップロードします。あるいは、[No spec] を選択して現在の仕様を解除することもできます。

6. [Update Snapshot] をクリックします（[No Spec] を選択した場合は [Remove Snapshot] をクリックします）。

選択した仕様から API リファレンス ドキュメントが生成され、API リファレンス ページに追加されます。

ポータル上の API を公開または公開停止する

ポータル上の API を公開または公開停止するには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。
   または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。
3. 公開または公開停止する API にカーソルを合わせます。
4. をクリックします。
5. ポータル上の API を公開するには、[Enabled] チェックボックスをオンにします。API の公開を停止するには、[Enabled] をオフにします。
6. [Save] をクリックします。

ポータル上の API のオーディエンスを管理する

ポータル上の API のオーディエンスを管理するため、次のいずれかにアクセスを許可できます。

• すべてのユーザー
• 登録ユーザーのみ

ポータル上の API のオーディエンスを管理するには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。
   または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。
3. オーディエンスを管理する API にカーソルを合わせて、操作メニューを表示します。
4. をクリックします。
5. [Audience] で、次のいずれかのオプションを選択します。
   • Anonymous users: すべてのユーザーに API プロダクトの閲覧を許可します。
   • Registered users: 登録ユーザーのみに API プロダクトの閲覧を許可します。
6. [Save] をクリックします。

ポータルから API を削除する

ポータルから API を削除するには:

1. [Publish] > [Portals] を選択し、目的のポータルを選択します。
2. ポータルのホームページで [APIs] をクリックします。
   または、上部のナビゲーション バーにあるポータル プルダウン メニューから [APIs] を選択します。
3. リスト内の API にカーソルを合わせて、操作メニューを表示します。
4. をクリックします。

公開された API に関する問題のトラブルシューティング

[Try It] の使用中に TypeError: Failed to fetch エラーが返された場合は、次の考えられる原因と解決策を検討します。

• 混合コンテンツ エラーの場合、そのエラーは swagger-ui の既知の問題が原因である可能性があります。可能な回避策のひとつは、OpenAPI 仕様の schemes 定義で HTTPS を HTTP より前に指定することです。次に例を示します。

   schemes:
     - https
     - http
  

• CORS（クロスオリジン リソース シェアリング）制限によるエラーの場合は、API プロキシに CORS のサポートを追加します。CORS は、クライアント側のクロスオリジン リクエストを可能にする標準メカニズムです。API プロキシへの CORS サポートの追加をご覧ください。また、ブラウザで CORS が使用可能であることも確認してください。