API の公開

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

API 公開の概要

API をポータルに公開する手順は、次の 2 ステップです。

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

ポータルに公開されるもの

API を公開すると、ポータルが自動的に次のように更新されます。
  • SmartDocs API リファレンス ドキュメントがポータルに追加される

    SmartDocs API リファレンス ドキュメントは OpenAPI 仕様のスナップショットからレンダリングされます。SmartDocs UI は、Angular Material という最先端の UI コンポーネント ライブラリに基づいています。

    デベロッパーは SmartDocs API リファレンス ドキュメントを読み、[Try this API] パネルから API リクエストを発行して出力を確認できます。[Try this API] パネルは、セキュアでないエンドポイント、または基本認証、API キー認証、OAuth 認証のいずれかを使用したセキュアなエンドポイント（どの認証タイプが使用されるかは OpenAPI 仕様で定義されたセキュリティ方法によります）に対応しています。OAuth の場合は、認可コード、暗黙、パスワード、クライアント認証情報のフローがサポートされています。

    をクリックすると、[Try this API] パネルが拡大します。パネルを拡大すると、curl の呼び出しとコードサンプル（HTTP、Python、Node.js などさまざまな形式があります）を見ることができます（次の図を参照）。

  • API リファレンス ドキュメントへのリンクが API ページに追加される

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

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

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

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

仕様エディタを使用して OpenAPI 仕様を作成する場合や、ポータルで SmartDocs を使用してインタラクティブな API リファレンス ドキュメントを生成する場合（後述）、Apigee Edge は OpenAPI 仕様 3.0 をサポートしていますが、一部の機能がまだサポートされていません。詳細については、統合ポータルに関する既知の問題をご覧ください。

コールバック URL について

OAuth 2.0 認可コード権限付与タイプ（「3-legged OAuth」と呼ばれることもあります）を使用するときなど、アプリにコールバック URL が必要な場合は、アプリを登録するデベロッパーにコールバック URL を指定するよう求めることができます。このコールバック URL では通常、クライアント アプリの代わりに認可コードを受け取るアプリの URL を指定します。詳細については、認可コード権限付与タイプを実装するをご覧ください。

注: コールバック URL は、対応する Edge アプリ エンティティにカスタム属性として保存されます。サードパーティ ID プロバイダを使用する場合、コールバック URL メタデータの同期はお客様側で行っていただく必要があります。

アプリの登録時にコールバック URL を要求するかどうかは、API をポータルに追加するときに構成できます。この設定はいつでも変更できます。API のコールバック URL を管理するをご覧ください。

アプリを登録するとき、デベロッパーは、コールバック URL を必要とするすべての API に対してコールバック URL を入力する必要があります。アプリを登録するをご覧ください。

「Try this API」をサポートするように API プロキシを構成する

API を公開する前に、SmartDocs API リファレンス ドキュメントの [Try this API] パネルでのリクエストを API プロキシがサポートするように構成する必要があります。

  • API プロキシに CORS サポートを追加して、クライアント側のクロスオリジン リクエストを可能にする

    CORS は、ウェブページで実行される JavaScript XMLHttpRequest（XHR）呼び出しがオリジン以外のドメインのリソースとやり取りできるようにする標準メカニズムです。CORS は、すべてのブラウザに組み込まれている「同一オリジン ポリシー」に対する一般的な解決策です。

  • API プロキシの構成を更新する（Basic 認証または OAuth2 を使用している場合）

次の表は、SmartDocs API リファレンス ドキュメントの [Try this API] パネルをサポートするための API プロキシの構成要件を、認証方法に基づいてまとめたものです。

認証方法 ポリシーの構成要件
なし、もしくは API キー API プロキシに CORS サポートを追加します。利便性を高めるために、GitHub に用意されているサンプル CORS ソリューションを使用するか、API プロキシへの CORS サポートの追加の説明に従ってください。
Basic 認証 次の手順を行います。
  1. API プロキシに CORS サポートを追加します。GitHub に用意されているサンプル CORS ソリューションを使用するか、API プロキシへの CORS サポートの追加の説明に従うと便利です。
  2. [Add CORS AssignMessage] ポリシーの Access-Control-Allow-Headers ヘッダーに authorization 属性が含まれていることを確認します。例:
    
<Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
OAuth2
  1. API プロキシに CORS サポートを追加します。GitHub に用意されているサンプル CORS ソリューションを使用するか、API プロキシへの CORS サポートの追加の説明に従うと便利です。
  2. [Add CORS AssignMessage] ポリシーの Access-Control-Allow-Headers ヘッダーに authorization 属性が含まれていることを確認します。例:
    
<Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
  3. OAuth2 ポリシーの RFC に準拠していない動作を修正します。GitHub で提供されているサンプル OAuth2 ソリューションを使用するか、次の手順を行うと便利です。
    • OAuth2 ポリシーの <GrantType> 要素が request.formparam.grant_type（フォーム パラメータ）に設定されていることを確認します。詳細については、<GrantType> をご覧ください。
    • OAuth2 ポリシーの token_type がデフォルトの BearerToken ではなく Bearer に設定されていることを確認します。

APIs ページにアクセスする

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

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

API リファレンス

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

API をポータルに追加する

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

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. [+ API] をクリックします。

    [Add API Product to Portal] ダイアログが表示されます。

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

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

  6. [Documentation] タブで、API リファレンス ドキュメントの内容とその公開設定を構成します。

    項目 説明
    API documentation source スナップショットに使用するソースを選択します。[Select an OpenAPI Spec] を選択して、仕様を選択またはアップロードします。または、[No API documentation] を選択して、API の追加後にドキュメントを追加します。仕様のスナップショットを管理するをご覧ください。
    Visibility

    デベロッパー チームおよびオーディエンス管理機能のベータ版リリースに登録していない場合は、次のいずれかのオプションを選択します。

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

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

    デベロッパー チームおよびオーディエンス管理機能のベータ版リリースに登録している場合は、次のいずれかのオプションを選択します。

    • Public (visible to anyone): すべてのユーザーが API を閲覧できます。
    • Authenticated users: 登録ユーザーのみに API の閲覧を許可します。
    • Selected audience: API の閲覧を許可するオーディエンスを選択します。

    公開設定は、ポータルで API の公開設定を管理するにあるように、後で管理することもできます。

    Status[Published] を選択して、API をポータルに公開します。API を公開する準備ができていない場合は、[Unpublished] を選択します。この設定は、ポータル上の API を公開または公開停止するにあるように、後で変更することもできます。

  7. [カスタマイズ] タブで次の情報を設定します。

    項目 説明
    TitleAPI のタイトルを更新します。デフォルトでは、API プロダクトの名前が使用されます。
    DescriptionAPI の説明を更新します。デフォルトでは、API プロダクトの説明が使用されます。
    API Product Image API ページの API カードに画像を表示するには、[Select an image] をクリックします。[Select image] ダイアログで、既存の画像を選択するか、新しい画像をアップロードする、もしくは外部画像の URL を指定します。画像は、ポータル上の API カードの画像を管理するにあるように、後で追加することもできます。

    注: API カード画像のサイズは、デフォルト テーマで 344 ピクセル x 192 ピクセルと定義されています。必ずこれと同じ相対サイズの画像を選択してください。あるいは、API カードの画像サイズを変更することもできます。詳細については、API ページにある API カードの外観をカスタマイズするをご覧ください。

    Callback URLアプリ デベロッパーにコールバック URL を指定するよう求める場合は、[Require app owners to specify a callback URL] を選択します。コールバック URL は、API のコールバック URL を管理するにあるように、後で追加または更新できます。

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

仕様のスナップショットを管理する

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

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

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. スナップショットを撮る API にカーソルを合わせて、操作メニューを表示します。

  4. スナップショット アイコン をクリックします。

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

  5. [Update API documentation source] プルダウンから既存の仕様を選択するか、[Select an OpenAPI Spec] を選択して API のドキュメントの生成に使用する新しい仕様を選択またはアップロードします。

    あるいは、[No API documentation] を選択して現在の仕様を解除することもできます。

  6. [Update Snapshot] をクリックします（[No API documentation] を選択した場合は [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 の公開設定を管理するため、次のいずれかにアクセスを許可します。

  • 一般公開（誰でも閲覧可能）
  • 認証済みユーザー
  • 選択したオーディエンス

ポータルのオーディエンスを作成および管理するには、ポータルのオーディエンスを管理するをご覧ください。

ポータル上の API の公開設定を管理するには:

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. 公開設定を管理する API にカーソルを合わせて、操作メニューを表示します。

  4. をクリックします。

  5. 次のいずれかのオプションを選択します。

    • Public (visible to anyone): すべてのユーザーが API プロダクトを閲覧できます。
    • Authenticated users: 登録ユーザーのみに API プロダクトの閲覧を許可します。
    • Selected audience: API プロダクトの閲覧を許可するオーディエンスを選択します。

  6. [Submit] をクリックします。

API のコールバック URL を管理する

API のコールバック URL を管理します。コールバック URL についてをご覧ください。

API のコールバック URL を管理するには:

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. コールバック URL を管理する API にカーソルを合わせて、操作メニューを表示します。

  4. 設定アイコン をクリックします。

  5. 認証 API のコールバック URL を必要に応じて更新します。

  6. [Save] をクリックします。

API カードの画像を管理する

API ページの API カードに表示される画像を追加または変更できます。

API カードの画像を管理するには:

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. 画像を管理する API にカーソルを合わせて、操作メニューを表示します。

  4. 設定アイコン をクリックします。

  5. [Image] で、次の操作を行います。

    • 現在の画像を削除する場合は [Remove] をクリックします。
    • 画像を選択またはアップロードする場合は [Select] をクリックします。

  6. [Save] をクリックします。

API の詳細を編集する

API の詳細を編集するには:

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. 編集する API にカーソルを合わせます。

  4. 設定アイコン をクリックします。

  5. 必要に応じて、項目を編集します。

  6. [Save] をクリックします。

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

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

  1. [Publish] > [Portals] を選択し、目的のポータルを選択します。

  2. ポータルのホームページで [APIs] をクリックします。

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

  3. リスト内の API にカーソルを合わせて、操作メニューを表示します。

  4. 削除 をクリックします。

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

以下のセクションでは、公開されている API のエラーのトラブルシューティングについて説明します。

Try this API を使用した際に返される Failed to fetch エラー

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

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

     schemes:
   - https
   - http

  • クロスオリジン リソース シェアリング（CORS）制限によるエラーの場合は、API プロキシに CORS のサポートを追加します。CORS は、クライアント側のクロスオリジン リクエストを可能にする標準メカニズムです。「Try this API」をサポートするように API プロキシを構成するをご覧ください。

Request header field not allowed エラー

[Try this API] の使用中に、次の例のような Request header field not allowedエラーが発生した場合は、CORS ポリシーでサポートされているヘッダーを更新する必要があります。例:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

この例では、content-type ヘッダーを [CORS AssignMessage] ポリシーの Access-Control-Allow-Headers セクションに追加します。新しい API プロキシへの Add CORS ポリシーの添付をご覧ください。

OAuth2 を使用して API プロキシを呼び出す際の Access denied エラー

Apigee の OAuthV2 ポリシーは、RFC に準拠していない特定のプロパティを含むトークンのレスポンスを返します。たとえば、このポリシーは、予想される RFC 準拠の値 Bearer ではなく、値が BearerToken のトークンを返します。この無効な token_type レスポンスにより、[Try this API] を使用するときに Access denied エラーが発生することがあります。

この問題を解決するには、JavaScript または AssignMessage ポリシーを作成して、ポリシーの出力を準拠する形式に変換します。詳しくは、RFC に準拠していない動作をご覧ください。