第1章 API の起動

このガイドは、3scale で API のブーストを開始するのに役立ちます。

ここでは、API を公開するための以下の主要手順について説明します。

API を保護する。
アプリケーションプランにより API へのアクセスポリシーを 設定する。
デベロッパーポータルを通じて開発者を 参加させる。
実稼働環境に移行する。

以下に示す 3 つのオプションから、API 公開のパスを選択することができます。

プロトタイプ
所要時間: 1 時間以内
目的*: 3scale とシンプルなパブリック API のインテグレーションをエンドツーエンドで完了する。
対象: プロトタイプパスは、最短の時間で 3scale とのインテグレーション方法の概要を把握し、3scale のエンドツーエンドの機能を理解する場合に推奨されます次に説明するベーシックパスの手順を実施する前に、このパスを実施する必要があります。管理ポータルの導入ウィザードを正常に完了している場合には、このパスを省略して次のパスに進むことができます。
ベーシック
所要時間: 1 週間以内
目的: API を実稼働環境で公開するための操作手順をすべて完了する。
対象: API を実稼働環境で公開したいが時間が限られている場合には、このベーシックパスにより必要な操作のほとんどがカバーされます。
アドバンスト
所要時間: 数週間
目的: ベーシックパスを完了した後のオプション操作。API の高度なコントロールおよびデベロッパーポータルの複雑なカスタマイズが可能。
対象: 要求がより複雑である、またはベーシックパスをすでに完了している場合には、アドバンストのオプションの検討が必要な場合があります。カスタムドメインおよび電子メール (SaaS の場合) を使用する場合には、リードタイムが長いので、実稼働環境への移行セクションの手順に従って早期に準備する必要があります。

期間のガイドラインは、API の複雑さや作業に割くことのできるリソースにより異なります。ほとんどの時間は、API の調整およびデベロッパーポータルコンテンツの準備に費やされます。安定した API およびドキュメントのコンテンツがすでに用意されている場合には、1 週間で実稼働環境に移行することができます。

1.1. API の保護、管理、およびプロモート

プロトタイプ、ベーシック、および アドバンスト パスの手順を個別にエンドツーエンドで実施することもできますし、必要に応じて異なる 3 つのパスから部分的に手順を抜き出して実施することもできます。それぞれのパスは互いに独立していますが、プロトタイプ、ベーシック、および アドバンスト パスは、順に積み上げて高度な設定を行うことが可能です。

1.1.1. プロトタイプ

1.1.1.1. API の保護

API が一般に公開されている (Saas の場合)、あるいは 3scale AMP システムからアクセス可能である (オンプレミスの場合) なら、数分でプロトタイプの 3scale アクセス制御レイヤーを設定することができます。

ここでは、パブリック API の例として Echo API を使用します。これは、任意のパスを受け入れてレスポンスのボディーでリクエストに関する情報 (パス、リクエストパラメーター、ヘッダー等) を返すシンプルな API です。Echo API には https://echo-api.3scale.net の URL からアクセスすることができます。

API にアクセス可能であることを確認します (セキュリティーレイヤー実装後は、バックエンドホストを隠したりアクセスを制限したりすることができます)。たとえば、https://echo-api.3scale.net/v1/fast/track。
[Your_API_name] > Integration > Configuration の順に移動します。
ご自分の API を設定する前に、デフォルトパラメーターを使用してテストコールが可能であることを確認します。
検証後、プライベートベース URL を入力します。例: https://echo-api.3scale.net:443。
テストコールを行うには、有効な GET リクエストの URL パスを入力し (例: /v1/fast/track)、続いて Update & Test Staging Environment をクリックします。
デフォルトクレデンシャルとして user_key が含まれる cURL ステートメントをコピーして、コマンドラインから呼び出しを行います。
```
curl "https://api-2445581407825.staging.apicast.io:443/v1/fast/track?user_key=287d64924e6120d215b1000ac07c063b"
```
異なる呼び出しを行うことができます。たとえば、同じ user_key を追加して、別のエンドポイントに対する呼び出しを行います。
注記
いずれかの開発者アカウントのアプリケーションの詳細ページから、API キーを取得することができます。
3scale のアクセス制御レイヤーにより、認証された呼び出しだけがご自分のバックエンド API にアクセスできるようになります。

1.1.1.2. アプリケーションプランによる API アクセスポリシーの設定

前項の手順で、認証された呼び出しだけがご自分の API にアクセスできるようにしました。本セクションでは、ポリシーを適用して流量制御を変更します。

3scale では、アプリケーション により API にアクセスするためのクレデンシャルが定義されます。アプリケーションには必ず 1 つ アプリケーションプラン が関連付けられ、アクセスポリシーが定義されます。アプリケーションは、開発者アカウント 内に保管されます。3scale の Basic プランで許可されるアプリケーションは 1 つだけですが、より高度なプランではアカウントごとに複数のアプリケーションが許可されます。

以下の例では、前項で使用した Echo API にポリシーを追加します。

[Your_API_name] > Applications > Application Plans の順に移動します。
Application Plans セクションで Basic アプリケーションプランに進み、3scale のインストールまたはサインアップ後にサンプルデータから生成されたプランのいずれかを編集します。
Hits 行で Limits を選択し、1 時間あたり 3 回の新しい使用限度を作成します。
[Your_API_name] > Applications > Listing の順に移動し、サンプルアプリケーションを 1 つ選択します。アプリケーションが Basic プランに設定されていることを確認します。設定されていなければ、アプリケーションの詳細ページで プランを変更します。
このアプリケーションのクレデンシャルを使用して、上記のサンプルコールを少なくとも 3 回繰り返します。

これで、基本プランのすべてのアプリケーションに対して、より制限の厳しいアクセスポリシーが正しく定義されました。

1.1.1.3. デベロッパーポータルを通じた開発者の参加

プロトタイプでは、何らかのドキュメントコンテンツを作成する必要はありません。通常は、ワークフローが要求に適合していることを確認するだけで十分です。たとえば、API が開発/テスト段階の間は、完全なセルフサービスワークフローを無効にすることができます。

管理ポータルから Audience セクションに移動し、Developer Portal メニューの Visit Portal のリンクをクリックします。
テストサインアップを作成し、すべての手順を実施します。
通常、セルフサービスはデフォルトで有効になっています。この設定を変更するには、Audience > Accounts > Usage Rules の順に移動し、Account approval required のチェックボックスをクリックします。
テストサインアップの手順をすべて繰り返し、ユーザーがログインするには管理ポータルでアカウントを承認しなければならないことを確認します。

これで、デベロッパーポータルのワークフローをカスタマイズできるようになりました。

1.1.2. ベーシック

1.1.2.1. API の保護

実稼働環境向けの完全な実装のためには、API の設定および 3scale とのインテグレーション方法に関して、基本方針を決定する必要があります。

API トラフィックの認証モードには、いくつかの選択肢があります。利用可能なオプションに関するガイドを確認し、設定を行ってください。

重要

設定を行ったら、再度認証モードを切り替えないでください。既存のクレデンシャルが無効になってしまうためです。

API トラフィックマネージャーレイヤーのデプロイメントにも、いくつかのオプションがあります。設定の容易さとパフォーマンスのバランスから、3scale ユーザーの間では APIcast (NGINX ベースの API ゲートウェイ) が好まれています。Hosted APIcast を使用すればすぐに運用を開始することができますが、ボリュームの制約やレイテンシー増加の問題が生じます。一方、APIcast を専用のサーバーにデプロイすれば、最高のパフォーマンスが得られ、トラフィックボリュームの制約から完全に解放されます。

Hosted APIcast

管理ポータルへの初回ログイン後に、導入ウィザードの手順に従います。
実稼働環境用として適切なバージョンが得られるまで、API 設定を繰り返します (アクセスポリシーの調整など)。
APIcast 設定を実稼働環境用ゲートウェイにプロモートします。

Self-managed APIcast

OpenShift サーバー上に、API ゲートウェイのテスト用システムを設定します。
実稼働環境用として適切なバージョンが得られるまで、API 設定を繰り返します (アクセスポリシーの調整など)。
APIcast 設定を実稼働環境用ゲートウェイにプロモートします。
Self-managed APIcast の詳細な情報は、APIcast のインストールを参照してください。また、APIcast ポリシーには、API のアクセスポリシーを設定する際の概念が記載されています。

1.1.2.1.1. アプリケーションプランによる API アクセスポリシーの設定

前項の操作で、認証された呼び出しだけがご自分の API にアクセスできるようにしました。本セクションでは、ポリシーを適用して流量制御を変更します。

3scale では、アプリケーション により API にアクセスするためのクレデンシャルが定義されます。アプリケーションには必ず 1 つ アプリケーションプラン が関連付けられ、アクセスポリシーが定義されます。アプリケーションは、開発者アカウント 内に保管されます。3scale の Basic プランでは、1 つのアプリケーションしか許可されません。より高度なプランでは、アカウントごとに複数のアプリケーションが許可されます。

プロトタイプ では、API の総ヒット数に基づいてアクセスを制御することしかできません。カスタムメソッドおよびメトリクスを使用して初めて、3scale の柔軟性を体感することができます。カスタムメソッドおよびメトリクスを使用することで、アプリケーションプランおよび API の分析をより高度化することができます。詳細は、解析に関するガイドを参照してください。

重要

API の構造と 3scale のメソッドまたはメトリクスとの間のマッピングは論理的です。整合性のとれたルールを定義すれば、3scale から API の使用状況に関するレポートを受け取ることができます。詳細さのレベルを決める必要があります。一般的には、5 - 20 メソッド/メトリクスを目標とすれば良いでしょう。
3scale に報告される値は、増加するだけです。絶対値を設定したりカウンターを減らしたりすることはできません。
新たなメソッドまたはメトリクスを 3scale に追加したら、インテグレーションポイント (API ゲートウェイまたはコードプラグイン) に新しいシステム名を追加することが重要です。
実行時に、再デプロイせずに流量制御などに変更を加えることができます。

この例では、Echo API のアプリケーションプランにポリシーを追加するには、次の手順を実行します。

対象の API を選択します。
Application Plans セクションで Basic を選択し、3scale へのサインアップまたはインスタンスのデプロイ後に自動的に生成されたプランのいずれかを編集します。
Hits に流量制御を設定している場合には、その設定を削除します。
プランの Hits メトリックに 新規メソッド を追加し、システム名を test に設定します。
test メソッドの流量制御を 1 時間あたり 5 回に設定します。
2 つの 新規メトリクス を追加し、システム名を v1 および v2 に設定します。
v2 メトリックの Enabled 列をクリックし、アクセスを無効にします。これは、流量制御をゼロに設定するのと同じ効果を持ちます。

APIcast のデプロイメント

[Your_API_name] > Integration > Configuration の順に移動します。
MAPPING RULES セクションを展開し、以下のマッピングを追加します。
注記
/のデフォルトのマッピングは削除されています。引き続き使用すると、ヒット数が二重にカウントされます。

コードプラグインのデプロイメント

3scale の承認およびレポート呼び出しにカスタムメソッドおよびメトリクスの使用状況を追加するには、プラグインライブラリーの手順および例に従ってください。
URL 構造からカスタムメソッド test へのマッピングを確認します。
URL からカスタムメトリクス v1 および v2 へのマッピングを確認します。
基本プランに関連付けられたアプリケーションのクレデンシャルを使用して、呼び出しをテストします。
- 呼び出しは許可されます。
```
curl "https://api-2445581407825.staging.apicast.io:443/v1/test?user_key=287d64924e6120d215b1000ac07c063b"
```
  5 回目以降は、呼び出しが拒否されます。これは、test メソッドに設定した制限のためです。
- Basic プランでは v2 は許可されないので、呼び出しは拒否されます。
```
curl "https://api-2445581407825.staging.apicast.io:443/v2/test?user_key=287d64924e6120d215b1000ac07c063b"
```
- missing に設定されたマッピングルールがないので、呼び出しは拒否されます。
```
curl "https://api-2445581407825.staging.apicast.io:443/missing?user_key=287d64924e6120d215b1000ac07c063b"
```
- 以下の呼び出しは、NGINX に対して許可されます (プラグインのマッピングの実装状態によります)。以下の呼び出しで 404 not found のレスポンスが返されるかどうかは、お使いのアプリケーションによります。これを避けるには、マッピングを調整してください。
```
curl "https://api-2445581407825.staging.apicast.io:443/noversion/test?user_key=287d64924e6120d215b1000ac07c063b"
```

この基本概念により、きわめて柔軟に API レイヤーを定義することができます。カスタムメソッドおよびメトリクスに何を使うかについて、早期に決定しておくことが重要です。システム名に変更を加えた場合には、API の保護セクションで説明したように、必ず変更を再デプロイする必要があります。

1.1.2.2. デベロッパーポータルを通じた開発者の参加

デベロッパーポータルの作成および使用については、関連のドキュメントを参照してください。コンテンツを Textile または Markdown で記述することを検討してください。オプションとして考慮すべき項目を以下に示します。

ドキュメントにインタラクティブ機能を追加して開発者のドキュメント作業を容易にするために、ActiveDocs を設定する。
ファビコンを追加する。
CMS で partial セクションの analytics を編集して、Google Analytics トラッカーコードを追加する。
サインアップのワークフローを設定する。
メールアドレスおよびメールテンプレートのコンテンツをカスタマイズする (共に SaaS ドキュメントを参照)。

1.1.3. アドバンスト

1.1.3.1. API の保護

高度な認証モード: OpenID Connect

OpenID Connect とのインテグレーションを通じた APIcast と Red Hat Single Sign-On (RH-SSO) の組み合わせにより、API を保護します。Red Hat 3scale API Management Platform のアプリケーションは、アイデンティティープロバイダー (IdP) (この場合は RH-SSO) と同期されます。現在、これはエンドツーエンドでサポートされるソリューションです。メインの OAuth 2.0 フロー (認可コード、リソースオーナーパスワード、クライアントクレデンシャル、およびインプリシット付与) に対応します。

コードプラグインのデプロイメント

3scale ユーザーのほとんどは、パフォーマンスに問題はないと感じています。ただし、API の処理を高速化したい場合には、好みのキャッシングライブラリーを使用して 3scale への承認コールをキャッシュすることができます。

1.1.3.2. アプリケーションプランによる API アクセスポリシーの設定

アラートを設定して、通知を電子メールで送付したり Web コンソールに表示したりすることができます。API Settings のページに移動します ([Your_API_name] > Integration > Settings)。ページの ALERTS セクションに移動します。ここで、必要なアラートを流量制御値のパーセンテージで設定することができます。

3scale では、流量制御をソフト制御 (上限を超えた呼び出しでも許容する) とするかハード制御 (アプリケーションにアクセスする前に呼び出しを拒否する) とするか、柔軟に設定することができます。コードプラグインでは、実装するタイプを意識的に決める必要があります。一方 APIcast の場合は、デフォルトではハード制御が定義されます。上限を超えた呼び出しが拒否されるのを防ぐために、Lua ファイルでこれらの制御をカスタマイズすることができます。

1.1.3.3. デベロッパーポータルを通じた開発者の参加

ベーシックパスの設定を完了している場合、以下の 2 つの項目についてデベロッパーポータルの高度な使用方法を検討することができます。

Liquid マークアップのタグおよびドロップにより、システムオブジェクトに直接アクセスすることができ、デベロッパーポータルページのダイナミックレンダリングが可能になります。
3scale のシステムページはすべてカスタマイズが可能です。ただし、HTML が複雑になるため、カスタマイズは熟達したユーザー向けです。極端に言えば、デベロッパーポータルのほとんどすべてのページをカスタマイズすることができます。しかしながら、一部の CSS を変更すれば、通常はデフォルトのページでまったく問題ありません。