API GatewayでGraphQL APIを効率的に管理する

Bobur Umurzokov

Bobur Umurzokov

March 21, 2023

Technology

GraphQL は、開発者がサーバーから必要なデータの構造を定義し、サーバーがそのデータのみを返すことを可能にする強力な API用クエリ言語 です。これにより、従来の REST API よりもはるかに効率的で柔軟なデータ取得が可能になります。REST API では同じデータを取得するために複数のリクエストが必要になることが多いですが、GraphQL ではその必要がありません。ただし、GraphQL API の管理は複雑で時間がかかる場合があり、特に大規模な場合にはその傾向が顕著です。そこで、API Gateway が役立ちます。

Apache APISIX のような現代のAPIゲートウェイの主要な機能の1つは、GraphQL API のサポートです。APISIX は、柔軟な設定システムと強力なプラグインを使用して、GraphQL API を簡単に管理およびスケーリングできます。そのようなプラグインの1つが degrapghql プラグインで、GraphQL API を REST API に変換することができます。この記事では、この機能を例を交えて探っていきます。

学習目標

この記事を通じて、以下の質問に対する答えを学び、見つけることができます：

  • DeGraphQL プラグインとは何か？
  • DeGraphQL プラグインのユースケースと機能は何か？
  • DeGraphQL プラグインの使用方法。
  • REST を GraphQL に変換する方法。
  • GraphQL API のトラフィックを管理する方法。

API Gateway で GraphQL API を管理する

DeGraphQL プラグインを使用する理由

このプラグイン は、URI を GraphQL クエリ にマッピングすることで、GraphQL アップストリーム（バックエンドサービス）によって公開された API を従来の REST エンドポイントに変換することができます。典型的なクライアントから REST API を呼び出すことで、GraphQL の利点をより多くの人々に提供できます。以下のユースケースを考えてみてください：

ユースケース 1: 既存の顧客が REST API を利用することに慣れており、GraphQL クエリの書き方にあまり詳しくない場合。彼らのためにシンプルに保つために、Apache APISIX API Gateway を使用して GraphQL API を REST API に変換できます。

ユースケース 2: フロントエンド開発チームに所属しており、バックエンドチームに新しい GraphQL サーバーの実装を依頼せずに、既存の GraphQL API 機能を試したい場合。

ユースケース 3: バックエンドを変更する権限がない場合。既存の GraphQL API セットがサードパーティによって管理されている可能性があります。

ユースケース 4: 既存の REST API インフラストラクチャを持っているが、GraphQL がニーズに合うかどうかを評価したい場合。

ユースケース 5: 大規模なコードベースを持っており、バックエンドで GraphQL への移行が進行中だが、待たずに GraphQL を使用したい場合。

ユースケース 6: 複数のマイクロサービスがあり、両方のアプローチを組み合わせて使用している場合。それらの間のスムーズな通信を有効にしたい場合。

DeGraphQL プラグインの機能

DeGraphQL プラグインは、GraphQL API を簡単に設定および管理するための 多くの便利な機能 を提供します。これには以下が含まれます：

リクエスト検証: 受信した GraphQL リクエストを検証し、特定の基準を満たしていることを確認できます。これには、クエリの構造のチェック、入力タイプの制約の強制などが含まれます。リクエストを検証することで、API が常に有効で適切に形成されたリクエストを受け取ることを保証できます。

クエリ解析: GraphQL クエリを解析し、クエリから特定の情報を抽出して API の動作を通知することができます。これには、要求されたデータに基づいて適切なバックエンドサービスを選択したり、特定のクエリパラメータに基づいて応答を変更したりすることが含まれます。

レスポンス変換: 最後に、クライアントに返される前に GraphQL レスポンスを変換できます。これは、データ構造の正規化、機密情報の削除、レスポンスに追加データを追加するなどに役立ちます。

この機能により、Apache APISIX は REST と GraphQL を簡単に使用できるだけでなく、レート制限を定義し、認証と認可を強制し、API を悪用しようとするクライアントをブロックし、API が更新されてもシームレスに動作することを保証できます。これらは他の 組み込みプラグイン の助けを借りて実現されます。

DeGraphQL プラグインの使用方法（デモ）

十分な理論的な知識を頭に入れたら、DeGraphQL プラグイン の実践的なデモに進むことができます。DeGraphQL は、クエリを実行するための GraphQL エンドポイントを必要とします。例として、国、大陸、言語に関する情報を取得する無料の公開 GraphQL API の1つである https://countries.trevorblades.com/ を使用します。

上記の Countries API リンクにアクセスすると、UI 上で GraphQL API に対してクエリを記述できるプレイグラウンドが開きます。

GraphQL API のクエリ

StepZen や ApollographQL が提供する GraphQL スタジオを使用して、独自の GraphQL API を構築することもできます。これにより、Accuweather、Airtable、GitHub、Twitter、Trello などの事前構築済み API を組み合わせて、独自の GraphQL API を構築およびデプロイできます。たとえば、Accuteweather と Countries API を組み合わせて、国/都市名によって提供される天気情報を収集し、APISIX を前面に配置して REST から API をクエリすることができます。

ここでのタスクは、上記のクエリ定義をシンプルな REST 呼び出しに変換し、JSON データとして送信することです。その結果、Apache APISIX API Gateway は REST エンドポイントを公開し、すべてのリクエストを GraphQL API にルーティングできるようになります。

たとえば、API Gateway の /country-info URI パスに対するすべての REST リクエストは、国コードによるクエリを基に変換され、GraphQL countries API https://countries.trevorblades.com/graphql に渡されるべきです。

以下のような curl コマンドの例：

curl -i http://127.0.0.1:9080/country-info  -X POST -d \
'{
   "code": "EE"
}'

そして、API からの応答は以下のようになります：

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "currency": "EUR",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

次のセクションでは、これを段階的に実現する方法を学びます。

Apache APISIX を起動する

degrapghql プラグインを使用する前に、Apache APISIX をインストールする必要があります。Apache APISIX のウェブサイトにある インストールガイド に従って始めることができます。

前提条件

  • Docker は、コンテナ化された etcd と APISIX をインストールするために使用されます。
  • curl は、APISIX にリクエストを送信して検証するために使用されます。Postman のような簡単なツールを使用して API とやり取りすることもできます。

APISIX は、以下のクイックスタートスクリプトで簡単にインストールおよび起動できます：

curl -sL https://run.api7.ai/apisix/quickstart | sh

これにより、設定を保存するための etcd と APISIX Gateway 自体の2つの Docker コンテナが作成されます。「✔ APISIX is ready!」というメッセージが表示されたら、APISIX の Admin API を使用して、GraphQL API にリクエストをプロキシするアップストリーム、プラグイン、ルートを設定できます。

アップストリームを作成する

次に、Countries GrapghQL API を API Gateway に登録するために Upstream オブジェクトを作成します：

curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -X PUT -d '
{
  "name": "GraphQL API upstream",
  "desc": "Register Countries GraphQL API as the upstream",
  "type": "roundrobin",
  "scheme": "https",
  "nodes": {
    "countries.trevorblades.com": 1
  }
}'

プラグイン設定を作成する

次に、新しい プラグイン設定 オブジェクトを設定します。ここでは、リクエストのホストと URI を書き換える proxy-rewrite プラグインと、GraphQL API にクエリを実行する degraphql プラグインの2つの変換プラグインを使用します。

curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -X PUT -d '
{
   "plugins":{
      "proxy-rewrite":{
         "uri":"/graphql",
         "host":"countries.trevorblades.com"
      },
      "degraphql":{
         "query":"query Country($code: ID!) {
                country(code: $code) {
                    code
                    capital
                    currency
                    languages {
                        name
                    }
                }  
          }",
         "variables":[
            "code"
         ]
      }
   }
}'

上記の DeGraphQL プラグイン設定では、query と variables の2つの属性を設定しています。GraphQL クエリ変数は、REST 呼び出しの Post リクエストボディまたは URI で定義できます。

この場合に実行するクエリは以下のようになり、独自のクエリに置き換えることができます：

query ($code: ID!) {
  country(code: $code) {
    code
    capital
    currency
    languages {
      name
    }
  }
}

DeGraphQL プラグインを使用したルートを作成する

このステップでは、プラグイン設定を使用する新しいルートを設定し、前のステップで作成したアップストリーム（ID を参照して）と連携するようにルートを設定します：

curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -X PUT -d '
{
   "name":"GraphQL API route",
   "desc":"Create a new route in APISIX for the Countries GraphQL API",
   "uri":"/country-info",
   "upstream_id":"1",
   "plugin_config_id":1
}'

DeGraphQL プラグインのアクティベーションをテストする

次に、以下の curl コマンドでこの新しい設定をテストします。

curl -i http://127.0.0.1:9080/country-info  -X POST -d \
'{
   "code": "EE"
}'

APISIX からの応答が得られます：

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "currency": "EUR",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

同じ code 変数を GET 引数として提供することもできます：

curl -i http://127.0.0.1:9080/country-info?code=EE

レスポンス変換

Apisix の response-rewrite プラグインを使用すると、クライアントに返される前に GraphQL レスポンスを変換できます。このプラグインを使用して、レスポンス JSON から currency キーと値を削除し、それ以外のすべてを表示するようにしましょう。そのためには、既存のプラグイン設定に response-rewrite プラグインを追加する必要があります。

curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -X PATCH -d '
{
  "plugins":{
   "response-rewrite": {
      "filters":[
        {
          "regex":"(?:\"currency\":\")(.*?)(?:\")",
          "scope":"once",
          "replace":""
        }
      ],
      "vars":[
        [
          "status",
          "==",
          200
        ]
      ]
   }
  }
}'

このプラグインをインストールした後、/country-info に再度リクエストを送信し、変換されたレスポンスを確認できます：

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

まとめ

全体として、DeGraphQL プラグインは、APISIX を使用して GraphQL API を構築する開発者にとって不可欠なツールです。その強力な機能と使いやすい設定により、既存の API ゲートウェイに簡単に統合でき、GraphQL 固有の機能をサポートすることで、API が高性能で信頼性が高く、スケーラブルであることを保証します。

関連リソース

Tags:
API Gateway Concept
GraphQL
Plugin