API Gateway로 GraphQL API를 효율적으로 관리하기

Bobur Umurzokov

Bobur Umurzokov

March 21, 2023

Technology

GraphQL은 개발자가 서버로부터 필요한 데이터의 구조를 정의할 수 있게 해주는 강력한 _API용 쿼리 언어_입니다. 서버는 이에 맞춰 해당 데이터만 응답합니다. 이는 종종 동일한 데이터를 검색하기 위해 여러 요청이 필요한 전통적인 REST API보다 훨씬 더 효율적이고 유연합니다. 그러나 GraphQL API를 관리하는 것은 복잡하고 시간이 많이 소요될 수 있으며, 특히 규모가 클 때 더욱 그렇습니다. 이때 API Gateway가 필요합니다.

Apache APISIX와 같은 현대적인 API Gateway의 주요 기능 중 하나는 GraphQL API를 지원한다는 점입니다. APISIX는 유연한 구성 시스템과 강력한 플러그인을 사용하여 GraphQL API를 쉽게 관리하고 확장할 수 있게 해줍니다. 그 중 하나인 degrapghql 플러그인은 GraphQL API를 REST API로 변환할 수 있게 해줍니다. 이 글에서는 이 기능을 예제와 함께 살펴보겠습니다.

학습 목표

이 글을 통해 다음 질문에 대한 답을 찾고 배울 수 있습니다:

  • DeGraphQL 플러그인이란 무엇인가?
  • DeGraphQL 플러그인의 사용 사례와 기능은 무엇인가?
  • DeGraphQL 플러그인을 사용하는 방법.
  • REST를 GraphQL로 변환하는 방법.
  • GraphQL API 트래픽을 관리하는 방법.

API Gateway로 GraphQL API 관리

DeGraphQL 플러그인을 사용하는 이유

이 플러그인은 GraphQL 업스트림(백엔드 서비스)에 의해 노출된 API를 URI를 GraphQL 쿼리에 매핑하여 전통적인 REST 엔드포인트로 변환할 수 있습니다. 일반 클라이언트에서 REST API를 호출하면 더 많은 사람들이 GraphQL의 이점을 누릴 수 있습니다. 다음 사용 사례를 고려해보세요:

사용 사례 1: 기존 고객이 REST API를 사용하는 데 익숙하고 GraphQL 쿼리를 작성하는 방법에 익숙하지 않습니다. 고객을 위해 간단하게 유지하기 위해 Apache APISIX API Gateway를 사용하여 GraphQL API를 REST API로 변환할 수 있습니다.

사용 사례 2: 프론트엔드 개발 팀에서 백엔드 팀에게 새로운 GraphQL 서버를 구현하도록 요청하지 않고 기존 GraphQL API 기능을 시도하고 싶습니다.

사용 사례 3: 백엔드를 변경할 수 없습니다. 이는 기존의 GraphQL API 세트이며, 잠재적으로 제3자에 의해 관리됩니다.

사용 사례 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 중 하나인 https://countries.trevorblades.com/를 사용할 것입니다.

위의 Countries API 링크로 이동하면, UI에서 GraphQL API에 대해 몇 가지 쿼리를 작성할 수 있는 플레이그라운드가 열립니다.

GraphQL API 쿼리

StepZen 또는 ApollographQL에서 제공하는 GraphQL 스튜디오를 사용하여 자신만의 GraphQL API를 구축할 수도 있습니다. 이는 Accuweather, Airtable, GitHub, Twitter, Trello 등과 같은 사전 구축된 API를 결합하여 자신만의 GraphQL API를 구축하고 배포하는 데 도움을 줍니다. 예를 들어, Accuweather와 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 자체를 저장하는 두 개의 Docker 컨테이너가 생성됩니다. "✔ APISIX is ready!" 메시지가 나타나면, APISIX의 Admin API를 통해 업스트림, 플러그인 및 라우트를 구성하여 GraphQL API로 요청을 프록시할 수 있습니다.

업스트림 생성

다음으로, Countries GrapghQL API를 API Gateway에 등록하기 위해 업스트림 객체를 생성합니다:

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를 다시 작성하고 GraphQL API에 쿼리를 만드는 데 각각 proxy-rewrite와 degraphql 두 변환 플러그인을 사용합니다.

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 두 속성을 설정했습니다. 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 Gateway에 쉽게 통합할 수 있게 해주며, GraphQL 특화 기능을 지원함으로써 API가 성능이 뛰어나고 안정적이며 확장 가능하도록 보장합니다.

관련 자료

Tags:
API Gateway Concept
GraphQL
Plugin