PR

3scaleの基本的な使い方

2019年7月4日(木)
田畑 義之

Step 3. 開発者ポータルを使ってみよう

ここまでの説明で、APIを公開し、APIのセキュリティを高めることまではできました。しかし、実際にAPIがどのような仕様なのか、どのように使えばよいのかが分からなければ、開発者はAPIを使ってくれません。ここでは、開発者がAPIを使ってくれるように、開発者向けのポータルを作成しましょう。

3scaleには、開発者ポータルのテンプレートが準備されています。“https://3scale.$(minishift-ip).nip.io”にアクセスしてみましょう(図23)。

図23:開発者ポータル(トップ画面)

トップ画面に加えて、開発者のクライアントアプリケーションのクレデンシャルを確認したり(図24)、

図24:開発者ポータル(アプリケーション)

使用量を分析したり(図25)、

図25:開発者ポータル(統計)

仕様を確認したりできます(図26)。

図26:開発者ポータル(ドキュメンテーション)

ここでは、トップ画面およびドキュメンテーションをHello API仕様に変更してみましょう。

API仕様の準備

開発者ポータルのドキュメンテーションにHello APIの仕様を表示するため、まずはHello APIの仕様を作成します。フォーマットにはSwagger 2.2.10を用います。

Hello APIの概要画面から[ActiveDocs]→[Create your first spec]を選択し、新規API仕様を作成しましょう(図27)。

図27:ActiveDocs作成画面

Hello APIの仕様は、次のようになります。

  {
      "swagger": "2.0",
      "info": {
          "version": "1.0.0",
          "title": "Hello API",
          "description": "This API returns the \"user_key\" query and the request headers."
      },
      "host": "hello-3scale-apicast-production.192.168.99.113.nip.io",
      "basePath": "/",
      "schemes": [
          "https"
      ],
      "consumes": [
          "application/json"
      ],
      "produces": [
          "application/json"
      ],
      "paths": {
          "/myapp/api/hello": {
              "get": {
                  "description": "Hello API",
                  "operationId": "hello",
                  "produces": [
                      "application/json",
                      "application/xml",
                      "text/xml",
                      "text/html"
                  ],
                  "parameters": [
                      {
                          "name": "user_key",
                          "in": "query",
                          "description": "Your API access key",
                          "required": false,
                          "x-data-threescale-name": "user_keys",
                          "type": "string"
                      },
                      {
                        "name": "access_token",
                        "in": "query",
                        "description": "Your access token",
                        "type": "string",
                        "required": true
                      }
                  ],
                  "responses": {
                      "200": {
                          "description": "response",
                          "schema": {
                              "$ref": "#/definitions/ResponseModel"
                          }
                      }
                  }
              }
          }
      },
      "definitions": {
          "ResponseModel": {
              "type": "object",
              "properties": {
                  "your_user_key": {
                      "type": "string"
                  },
                  "your_request_headers": {
                      "type": "object"
                  }
              }
          }
      }
  }

Hello APIをコールするためには、アクセストークンが必要になります。アクセストークンを取得するためのAPIの仕様も、Hello APIの仕様と同様の手順で作成します。

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "OAuth for Hello API",
    "description": "OAuth2.0 Client Credentails Flow for authentication of our Hello API."
  },
  "host": "keycloak-server.oss.example.co.jp:8443",
  "basePath": "/auth/realms/3scale/protocol/openid-connect",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/x-www-form-urlencoded"
  ],
  "paths": {
    "/token": {
      "post": {
        "description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
        "operationId": "oauth",
        "parameters": [
          {
            "name": "client_id",
            "description": "Your client id",
            "type": "string",
            "in": "formData",
            "required": true,
            "default": "9d1a338f"
          },
          {
            "name": "client_secret",
            "description": "Your client secret",
            "type": "string",
            "in": "formData",
            "required": true,
            "default": "xxx"
          },
          {
            "name": "grant_type",
            "description": "OAuth2 Grant Type",
            "type": "string",
            "required": true,
            "default": "client_credentials",
            "in": "formData"
          },
          {
            "name": "scope",
            "description": "Scopes",
            "type": "string",
            "required": true,
            "default": "openid",
            "in": "formData"
          }
        ],
        "responses": {
          "200": {
            "description": "response"
          }
        }
      }
    }
  }
}

ポータル画面の変更

次に、開発者ポータル画面を変更していきます。まずは、トップ画面のタイトルを”Echo API”から”Hello API”に変更し、ついでに画面の背景も青色から緑色に変更しましょう。

開発者ポータル画面を変更するには、管理ポータルのダッシュボードから[Audience]→[Developer Portal]→[Content]を選択します。[Homepage]にて、トップ画面のタイトルを変更します(図28)。

図28:開発者ポータル編集画面(Homepage)

[default.css]で、画面の背景を変更します(図29)。

図29:開発者ポータル編集画面(default.css)

変更を[Save]し、[Publish]すると、開発者ポータルに反映されます(図30)。

図30:開発者ポータル(変更後のトップ画面)

続けて、開発者ポータルのドキュメンテーションを変更します。ドキュメンテーションは[Documentation]で変更します。ここでは、アクセストークンを取得するためのAPIの仕様とHello APIの仕様を並べて表示するために、新しく”another-swagger-ui-container”というDOMを設けています(図31)。

図31:開発者ポータル編集画面(Documentation)

変更を[Save]し、[Publish]すると、開発者ポータルに反映されます(図32)。

図32:開発者ポータル(変更後のドキュメンテーション)

ここで、実際に開発者ポータルを用いてAPIを試し打ちしてみましょう。各APIをクリックすると、リクエストに必要なパラメータを入力できる欄が表示されます(図33)。クライアントIDとクライアントシークレットの欄には、開発者が持つクライアントアプリケーションのクライアントIDとクライアントシークレットを入力させても良いのですが、API仕様は広く一般に公開することも考えられるので、テスト用のクライアントアプリケーションを作成し、そのクライアントIDとクライアントシークレットをデフォルト値として入れておくのが親切でしょう。

図33:開発者ポータル(OAuth for Hello APIのリクエスト)

[Try it out!]を押下すると、リクエストおよびレスポンスが表示されます(図34)。

図34:開発者ポータル(OAuth for Hello APIのレスポンス)

続いて、Hello APIです。Oauth for Hello APIのレスポンスから取得したアクセストークンをパラメータに指定して、試し打ちしてみましょう(図35)。

図35:開発者ポータル(Hello APIのリクエスト)

[Try it out!]を押下すると、無事にHello APIからレスポンスが返ってきました(図36)。

図36:開発者ポータル(Hello APIのレスポンス)

以上で、Hello APIの仕様を開発者ポータルで公開することができました。

おわりに

次回は、APIcast(3scaleのAPIゲートウェイ)の機能を柔軟に拡張可能なポリシーという機能について紹介します。

株式会社 日立製作所
OSSソリューションセンタにて、API管理や認証周りのOSSの開発/サポート/普及活動に従事。3scaleのapicastリポジトリのコントリビュータであり、流量制御ポリシーやスコープチェックポリシーを中心に多数のコードをコミットしている。

連載バックナンバー

Think IT会員サービス無料登録受付中

Think ITでは、より付加価値の高いコンテンツを会員サービスとして提供しています。会員登録を済ませてThink ITのWebサイトにログインすることでさまざまな限定特典を入手できるようになります。

Think IT会員サービスの概要とメリットをチェック

他にもこの記事が読まれています