Prismatic이 API로 GraphQL을 선택한 5가지 이유

Prismatic는 B2B 소프트웨어 회사가 통합 워크플로우를 재사용하고 각 고객의 독특한 구성과 증빙서류를 처리하는 고객의 특정한 실례를 구축하는 통합 플랫폼이다.
Prismatic을 만들기 시작했을 때, 웹 응용 프로그램과 CLI를 사용할 수 있는 API가 필요합니다.또한 우리는 개발자 사용자가 자신의 수요에 따라 고객을 관리하고 통합할 수 있도록 프로그래밍 방식으로 우리의 API에 접근할 수 있기를 바란다.이것은 하나의 문제를 가져왔다. 서로 다른 개발자는 자연히 서로 다른 수요와 용례를 가지고 모든 사람의 수요를 위해 일련의 맞춤형 RESTful 단점을 만드는 것은 무의미하다.GraphQL이 점점 더 인기를 끌고 있습니다(충분한 이유가 있습니다!)우리의 수요를 감안하면 이것은 적당한 선택이다.
오늘 저는 API를 설계할 때의 사고 과정과 GraphQL이 왜 올바른 선택이라고 생각하는지 이야기하고 싶습니다.

GraphQL이란 무엇입니까?

우선 GraphQL이 무엇인지 살펴보겠습니다.SQL 데이터베이스에 익숙하면 GraphQL이 익숙해집니다.데이터베이스에 액세스하는 것이 아니라 API 노드에 액세스하는 쿼리 언어입니다.예를 들어, SQL 지원 응용 프로그램에서 통합 정보에 대한 질의는 다음과 같습니다.

SELECT id, name, description FROM integrations; 

GraphQL에서 API 끝점에 대해 유사한 질의를 수행할 수 있습니다.

query {
  integrations {
    nodes {
      id
      name
      description
    }
  }
}

데이터 수정 SQL 조회 (예: DELETE, UPDATE 는 GraphQL에서 유사한 구문을 사용합니다.GraphQL에서 "돌변"을 보낼 수 있으므로 유사한 작업을 수행하여 통합을 제거할 수 있습니다.

mutation {
  deleteIntegration(
    input: {
      id: "SW50ZWdyYXRpb246NjQxY2RhMmEtNzkwMi00YjYzLWJjZGEtMmE3NTk0Yzk1YTAy"
    }
  ) { integration { id } }
}

GraphQL을 선택해야 하는 이유

그렇다면 왜 우리는 API로 GraphQL을 선택합니까?간단하게 말하면 표준 RESTful API를 개발하는 것보다 더 빨리 작업할 수 있는 유연성을 준다.다음은 REST 대신 GraphQL을 선택하는 몇 가지 이점입니다.

1. 한 요청에서 조회한 내용을 정확하게 얻기

GraphQL을 사용하면 클라이언트 개발자로서 원하는 내용을 조회하고 요청한 내용을 정확하게 되돌릴 수 있습니다.한 개의 요청을 통해 여러 자원에 대한 정보를 요청할 수도 있고, 필요에 따라 모든 자원에 대한 가능한 한 많거나 적은 정보를 얻을 수도 있습니다.
이를 설명하기 위해 GraphQL과 REST를 어떻게 사용하는지 예를 들어 살펴보겠습니다.만약에 우리가 모든 통합된 명칭과 우리가 배치한 모든 통합된 고객의 이름을 열거하고 싶다면.만약 우리가 RESTful API를 가지고 있다면, 나는 우리가 이러한 정보를 수집하는 데 도움을 줄 수 있는 세 가지 단점이 있기를 바란다.

[GET] /integrations - 각 통합 이름, ID, 마지막 릴리즈 날짜 및 마지막 릴리즈를 포함하는 통합 목록을 반환합니다.

[GET] /integrations/<integration-id>/instances - 인스턴스의 ID, 이름, 배치된 고객의 ID를 포함하여 통합된 특정 인스턴스 목록을 반환합니다.

[GET] /customers/<customer-id> - 고객 이름, 작성 날짜 및 사용자 ID를 포함한 특정 고객에 대한 정보를 반환합니다.

우리는 /integrations로부터 통합에 관한 정보를 요청할 수 있다.그리고 모든 통합에 대해 우리는 /integrations/<integration-id>/instances 에서 배치 실례의 목록을 요청할 수 있다.마지막으로 모든 실례에 대해 우리는 /customers/<customer-id>에서 실례에 배치된 고객에 대한 정보를 요청할 수 있다.

우리는 이 모든 것을 할 수 있다...그러나 몇 가지 주요 문제점도 있다.

우리는 지나치게 정보를 얻는다.우리의 용례에 대해 우리는 마지막 발표 시간이나 발표자를 집적하는 것에 무관심하다.우리는 실례의 이름도 알 필요가 없고, 고객의 메타데이터(예를 들어 사용자 정보나 고객 창설 날짜)도 알 필요가 없다.우리가 진정으로 관심을 가지는 것은 통합된 명칭과 그들이 배치된 고객의 명칭이다.

저희가 얻은 정보가 부족합니다.만약 /integrations/<integration-id>/instances ID가 아닌 고객 이름이 생성된다면?이것은 다른 곳에서 과도한 캡처를 초래할 수 있지만, 이것은 우리로 하여금 고객 이름을 얻는 API 왕복 스케줄을 절약하게 할 것이다.

우리는 여러 차례 왕복을 했다.만약 우리가 50개의 집적을 가지고 있다고 가정하면, 집적마다 평균 20개의 고객에게 배치된다.우리는 /integrations 에게 한 통, /integrations/<integration-id>/instances 에게 50통, (50 integrations) x (20 instances) = 1000 에게 /customers/<customer-id> 전화를 할 것이다.1051회 API 호출 후에 필요한 정보를 얻을 수 있습니다.총체적

이런 과도하고 부족한 정보 획득에 통상적으로 말하는 API 개발N+1 Problem까지 합치면 1000개가 넘는 API 호출이 발생하여 이런 가설을 사용하는 RESTful API는 정말 불쾌하다.현재, 우리는 /gimme-just-integrations-and-customer-names라는 새로운 RESTful 노드를 만들 수 있었지만, 모든 개발자 사용자를 위해 유일한 RESTful 노드를 만들면 곧 유지할 수 없게 될 것이다.
반대로 GraphQL의 동일한 문제를 살펴보겠습니다.통합된 이름과 배치된 고객의 이름만 있으면 Prismatic API에 문의할 수 있습니다.

query {
  integrations {
    nodes {
      name
      instances {
        nodes {
          customer {
            name
          }
        }
      }
    }
  }
}

GraphQL 기본 API는 단일 요청에서 원하는 데이터를 포함하는 JSON 구조를 반환합니다.

{
  "data": {
    "integrations": {
      "nodes": [
        {
          "name": "Render Rocket in CAD",
          "instances": {
            "nodes": [
              {
                "customer": {
                  "name": "Mars Missions Corp"
                }
              },
              {
                "customer": {
                  "name": "Smith Rockets"
                }
              },
                            ...
            ]
          }
        },
                ...
      ]
    }
  }
}

이것은 1051개의 다른 API 요청을 보내는 것보다 훨씬 간단하고 절대적으로 빠르다!우리의 백엔드 서버도 1051이 아니라 단일 요청을 처리하는 것을 좋아한다.과도하고 캡처 부족, 여러 차례 왕복은 클라이언트 문제뿐만 아니라 서버 부하에도 영향을 미친다.

2. GraphQL은 자체 기록

일부 복잡한 API를 가진 회사는 전체 팀을 가지고 문서 유지보수Swagger, API 규범을 읽을 수 있는 문서로 전환하는 데 주력한다. GraphQL을 통해 자원이 어떻게 서로 연결되는지 정의할 수 있다(Primatic의 경우 하나의 통합은 여러 개의 실례가 있고 하나의 실례는 하나의 고객 등). 그리고 API와 관련된 모델을 자동으로 생성할 수 있다.또는 다른 방식을 선택할 수도 있습니다. - 일부 모델을 정의하면 백엔드에 캐시 항목과 모델이 자동으로 생성됩니다!
GraphQL API 클라이언트를 열면 클라이언트가 API의 패턴을 질의하므로 GraphQL 질의를 구축할 때 문서를 클릭하고 리소스 관계식과 속성을 볼 수 있습니다.

우리는 자동 생성 모드를 사용하고 이를 템플릿 엔진을 통해 생성합니다API docs.API의 발전과 새로운 기능이 추가됨에 따라 새로운 문서는 자동으로 생성되고 인공적으로 관여할 필요가 없습니다!문서는 자동으로 API와 동기화됩니다.

3. 패턴은 강한 유형이다

문서를 자동으로 생성하는 데 유용한 것 외에 생성하는 패턴은 강한 유형이기 때문에 검색이 어떤 응답을 받을지 확실하게 알 수 있습니다.모드는 String나 Float 같은 표량 유형을 사용해야 하는지 알려줄 뿐만 아니라 대상의 구조와 관계도 알려줄 수 있습니다.예를 들어 고객은 labels 유형의 String 목록을 가지고 있으며, 자신이 속한 org 유형의 Organization을 참조할 수 있다.많은 GraphQL 클라이언트 라이브러리에서 모드를 가져올 수 있기 때문에 저희 API의 응답은 당신이 가장 좋아하는 프로그래밍 언어의 강한 유형의 대상으로 변환할 수 있습니다. 이것들은 모두 API 모드에서 설명한 형식을 바탕으로 합니다.
내부적으로는 GraphQL API 모드를 사용하여 TypeScript 구조를 자동으로 생성합니다.이렇게 하면 노드 기반의 CLI 도구와 React 웹 응용 프로그램에 유형이 내장되어 있으며, TypeScript는 API와 응용 프로그램 사이의 유형이 일치하지 않는 오류를 포착할 수 있습니다.

4. 개발자가 신속하게 행동하도록 하기

웹 응용 프로그램과 CLI 도구를 구축하고 계속 추가할 때 API에서 다른 데이터 집합을 조회하고 있습니다.우리의 웹 응용 프로그램의 일부 페이지에서, 우리는 고객과 그들에게 배치된 실례를 열거해야 한다.다른 페이지의 경우, 이름이나 그것들에 대한 다른 데이터가 나타나지 않고 실례적인 ID만 필요합니다.이 페이지의 모든 맞춤형 RESTful 단점은 어리석은 것이다. 우리의 전단 개발자들은 후단 개발자들이 그들의 일을 완성하기를 기다릴 때 아무 일도 하지 않는다.반면 프런트엔드 개발자는 자신의 의사에 따라 자신의 GraphQL 조회를 설계할 수 있고 백엔드 개발자가 독립적으로 일할 수 있다.우리의 프런트엔드 개발자는 페이지에 표시된 데이터를 현저하게 변경할 수 있으며, 상응하는 백엔드 변경 기능 요청을 만들지 않는 상황에서 이러한 변경을 할 수 있다.

5. 고객 개발자는 특정한 언어나 도구에 국한되지 않는다

우리는 개발자 사용자들이 Prismatic CLI 도구를 사용하도록 권장하지만, 절대로 이렇게 하도록 요구하지 않는다.원하는 언어로 통합 배포를 관리할 수 있습니다. 대부분의 현대 언어는 한 가지 또는 여러 가지가 있습니다GraphQL clients.Linux 또는 MacOS 마니아인 경우 터미널에서 Prismatic API와 상호 작용할 수도 있습니다.

QUERY='{
  "query":
    "query { components { nodes { label description key authorizationRequired } } }"
}'

curl ${API_ENDPOINT} -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: bearer ${API_KEY}" \
    --data "$(echo $QUERY)"

Prismatic 웹 앱 및 CLI 도구와 동일한 API를 사용하므로 웹 앱 또는 CLI 도구를 사용하여 API를 사용하여 모든 작업을 수행할 수 있습니다.

각주 API 사용 방법

GraphQL을 선택한 이유를 설명한 만큼 Prismatic API를 사용하는 방법을 빠르게 알아보겠습니다.GraphQL을 사용하여 조회하는 가장 간단한 방법은 GraphiQL(그래픽 발음) 브라우저 도구in our docs를 사용하는 것입니다.웹 응용 프로그램에 로그인하면 이 브라우저 도구에 자동으로 로그인합니다.

explorer 도구는 GraphQL 쿼리와 돌연변이를 만드는 데 편리하게 도움을 줄 수 있습니다. 쿼리를 작성할 때 문서가 쿼리 옆에 표시되기 때문입니다.일단 저희 API에 익숙해지면 GraphQL 클라이언트 라이브러리를 가장 좋아하는 프로그래밍 언어로 사용하여 저희 API를 프로그래밍 방식으로 조회할 수 있습니다.API 영패를 어떻게 얻는지, 그리고 사용curl, curl 또는 python 조회 API의 예시를 보시기 바랍니다.