API

GraphQL이란?

GraphQL 개념 및 역할

GraphQL은 쿼리 언어이자 애플리케이션 프로그래밍 인터페이스(API)를 위한 서버측 런타임으로, 클라이언트에게 요청한 만큼의 데이터를 제공하는 데 우선 순위를 둡니다.

GraphQL은 API를 더욱 빠르고 유연하며 개발자 친화적으로 만들기 위해 설계되었습니다. GraphiQL이라 알려진 통합 개발 환경(Integrated Development Environment, IDE) 내에 배포될 수도 있습니다. REST를 대체할 수 있는 GraphQL은 개발자가 단일 API 호출로 다양한 데이터 소스에서 데이터를 끌어오는 요청을 구성할 수 있도록 지원합니다.

또한 GraphQL은 API 유지 관리자에게 기존 쿼리에 영향을 미치지 않고 필드를 추가하거나 폐기할 수 있는 유연성을 부여합니다. 개발자는 자신이 선호하는 방식으로 API를 빌드할 수 있으며, GraphQL 사양은 이러한 API가 예측 가능한 방식으로 작동하도록 보장합니다.

E-Book 보기: 효과적인 API 관리를 위한 7가지 핵심 사항

GraphQL 쿼리 언어: 스키마(schema) 및 리졸버(resolver) 개념

API 개발자는 GraphQL을 사용해 클라이언트가 서비스를 통해 쿼리할 가능성이 있는 모든 데이터를 설명하는 스키마를 생성합니다.

GraphQL 스키마는 개체 유형으로 구성되어 어떤 종류의 개체를 요청할 수 있으며 어떠한 필드가 있는지 정의합니다.

쿼리가 수신되면 GraphQL은 스키마에 대해 쿼리를 검증한 후 검증된 쿼리를 실행합니다.

API 개발자는 스키마의 각 필드를 리졸버라고 불리는 기능에 첨부합니다. 실행 중 값을 생산하기 위해 리졸버가 호출됩니다.

Graphql-spec 리포지토리에 명시된 API 쿼리 구문을 정의하고 검증하는 것 외에도 GraphQL은 대부분의 의사 결정을 API 설계자에게 맡깁니다. GraphQL은 개발자가 PHP(graphql-php), Scala(Sangria), Python(Graphene Python), Rub (graphql-ruby), JavaScript(graphql.js) 등을 사용할 수 있다는 식의 데이터 저장 방식이나 사용할 프로그래밍 언어에 대한 어떠한 지침도 제공하지 않습니다. 덕분에 네트워크, 인증, 페이지 분할 등의 필수 사항이 없습니다.

클라이언트 입장에서 가장 흔한 GraphQL 작업은 쿼리와 변형입니다. 이를 생성, 읽기, 업데이트, 삭제(CRUD) 모델로 생각해 보자면, 쿼리는 읽기와 동일한 과정입니다. 이외 모든 작업(생성, 업데이트, 삭제)는 변형을 통해 이루어집니다.

레드햇 웨비나 보기: API 기초 강의

API 설계 모범 사례: 신한은행, Red Hat과 협업하여 개방형 뱅킹을 위한 글로벌 오픈 API 플랫폼 구축

GraphQL 장점과 단점 비교

비즈니스나 엔터프라이즈 환경에서 GraphQL를 활용해 보려고 하시나요? 장점과 단점이 모두 존재합니다.

GraphQL 장점

GraphQL 스키마는 GraphQL 애플리케이션에 신뢰할 수 있는 단일 소스를 하나 설정합니다. 조직은 이를 통해 전체 API에 페더레이션할 수 있게 됩니다.
GraphQL 호출은 단일 왕복으로 처리되며 클라이언트는 오버페칭 없이 요청한 결과만 얻습니다.
엄격하게 정의된 데이터 유형은 클라이언트와 서버 간 통신 오류를 줄여줍니다.
GraphQL은 세부 검사를 수행합니다. 클라이언트는 사용 가능한 데이터 유형 목록을 요청할 수 있습니다. 자동 생성 문서의 경우 이상적인 방식이죠.
GraphQL은 애플리케이션 API가 기존 쿼리를 중단하지 않고도 진화할 수 있도록 허용합니다.
REST API로 사용할 수 없는 기능을 제공하기 위해 대부분의 오픈소스 GraphQL 확장 기능을 사용할 수 있습니다.
GraphQL은 특정 애플리케이션 아키텍처를 지정하지 않으므로 기존 REST API에 추가하여 기존 API 관리 툴과 연동할 수 있습니다.

GraphQL 단점

REST API에 친숙한 개발자의 경우 GraphQL를 학습하는 데 시간이 필요합니다.
GraphQL은 데이터 쿼리의 상당 작업을 서버측으로 옮겨 서버 개발자 작업의 복잡성이 커집니다.
구현 방식에 따라 GraphQL은 REST API가 아닌 다른 API 관리 전략을 필요로 할 수 있습니다. 이는 특히 비용 제한과 가격을 고려하는 경우 특히 그렇습니다.
캐싱이 REST보다 훨씬 복잡합니다.
API 유지관리자의 경우 유지 관리 가능한 GraphQL 스키마를 작성하기 위한 추가 태스크를 수행해야 합니다.

API를 통한 데이터 공유로 서비스 개선 달성 사례 보기

GraphQL 쿼리 예제

GraphQL을 파악하려면 샘플 쿼리와 그 응답을 살펴보는 것이 가장 좋습니다. GraphQL 프로젝트 웹사이트인 graphql.org에서 수정한 다음 3개의 예시를 살펴보겠습니다.

첫 번째 예시는 지정한 모양의 특정 필드를 반환하는 API를 요청해 클라이언트가 GraphQL 쿼리를 구성하는 방법을 보여줍니다.

{ me { name } }

GraphQL API는 다음과 같은 결과를 JSON 형식으로 반환합니다.

{ "me": { "name": "Dorothy" } }

클라이언트는 GraphQL 쿼리의 일부로 인수를 전달할 수 있습니다. 예시는 다음과 같습니다.

{ human(id: "1000") { name location } }

결과는 다음과 같습니다.

{ "data": { "human": { "name": "Dorothy, "location": "Kansas" } } }

여기서부터는 더욱 흥미롭습니다. GraphQL은 사용자에게 재사용 가능한 파편을 정의하고 변수를 할당할 수 있도록 합니다.

ID 목록을 요청해야 하며, 각 ID에 대한 일련의 기록을 요청해야 한다고 가정해 보겠습니다. GraphQL을 사용하면 단일 API 호출로 원하는 모든 요소를 풀링하는 쿼리를 구성할 수 있습니다.

다음과 같은 쿼리가 있다고 가정해 보겠습니다.

query HeroComparison($first: Int = 3) { leftComparison: hero(location: KANSAS) { ...comparisonFields } rightComparison: hero(location: OZ) { ...comparisonFields } } fragment comparisonFields on Character { name friendsConnection(first: $first) { totalCount edges { node { name } } } }

이는 다음과 같은 결과로 이어질 수 있습니다.

{ "data": { "leftComparison": { "name": "Dorothy", "friendsConnection": { "totalCount": 4, "edges": [ { "node": { "name": "Aunt Em" } }, { "node": { "name": "Uncle Henry" } }, { "node": { "name": "Toto" } } ] } }, "rightComparison": { "name": "Wizard", "friendsConnection": { "totalCount": 3, "edges": [ { "node": { "name": "Scarecrow" } }, { "node": { "name": "Tin Man" } }, { "node": { "name": "Lion" } } ] } } } }

GitHub 사용자라면 GitHub’s GraphQL Explorer를 통하는 것이 GraphQL를 접할 가장 빠른 방법입니다.

GraphQL과 오픈소스: Open API 및 Swagger

GraphQL은 Facebook에서 개발했으며 2012년에는 모바일 애플리케이션을 위해 사용되었습니다. GraphQL 사양은 2015년에 오픈소스로 공개되었으며 현재는 GraphQL Foundation이 감독하고 있습니다.

GraphQL과 관련된 다양한 오픈소스 프로젝트가 있습니다. 아래 기재된 목록이 전부는 아니며, GraphQL의 도입을 촉진하기 위해 설계된 프로젝트가 포함되어 있습니다.

Apollo: 프론트엔드 클라이언트 라이브러리(Apollo Client)와 백엔드 서버 프레임워크(Apollo Server)를 포함하는 GraphQL 플랫폼
Offix: 애플리케이션에 도달할 수 없는 경우에도 GraphQL 변형 및 쿼리를 실행할 수 있도록 허용하는 오프라인 클라이언트
Graphback: GraphQL 지원 Node.js 서버를 생성하기 위한 커맨드라인 클라이언트
OpenAPI-GraphQL: OpenAPI 사양 또는 Swagger로 설명된 API를 GraphQL로 번역하기 위한 커맨드라인 인터페이스 및 라이브러리

오픈 API 기술 전략 사례 보기

GraphQL 시작하기: Red Hat API 솔루션

애플리케이션 프로그래밍 인터페이스(Application Programming Interface, API) 관리 플랫폼

API 중심, 컨테이너 기반 아키텍처로 서비스를 분리하여 독립적으로 개발, 확장 및 배포

언어 선택