[웹 지식] GraphQL이란? (REST API vs GraphQL)

https://claremont.tistory.com/entry/%EC%9B%B9-%EC%A7%80%EC%8B%9D-API%EC%99%80-RESTful-API

[웹 지식] API와 RESTful API

 

GraphQL이란 API 설계 스타일 중 하나이며, 그중에는 우리가 흔히 아는 REST API 방법이 있다

API 설계 스타일 목록

 

 

 

ㅁGraphQL: Facebook이 개발한 API 쿼리 언어 및 실행 환경

REST API의 단점을 보완하고 더 유연한 데이터 요청을 가능하게 하는 기술이다

 

[GraphQL 특징]

① 클라이언트가 원하는 데이터만 요청

• REST API에서는 서버가 정해진 JSON 형식으로 응답하지만, GraphQL에서는 클라이언트가 원하는 데이터만 선택해서 요청할 수 있다 (불필요한 데이터를 받지 않으므로 네트워크 사용량 감소)

② 단일 엔드포인트 사용(/graphql)

• REST API는 여러 개의 엔드포인트 (/users, /posts, /comments 등)를 사용하지만, GraphQL은 단 하나의 엔드포인트(/graphql)를 통해 모든 데이터를 요청할 수 있다

③ 계층적 데이터 요청

• REST API는 여러 개의 요청을 보내야 하는 경우가 많지만, GraphQL은 한 번의 요청으로 관계형 데이터를 가져올 수 있다

④ 강력한 타입 시스템

• GraphQL은 스키마(Schema)를 기반으로 작동하며, 데이터 타입이 명확하게 정의된다

 

[GraphQL 기본 개념]

① 스키마(Schema): GraphQL API의 데이터 구조를 정의하는 곳

type User {
  id: ID!
  name: String!
  age: Int
}

type Query {
  getUser(id: ID!): User
}

 

• User 타입은 id, name, age 필드를 가진다
• Query 타입은 getUser라는 쿼리를 정의하고, User 데이터를 반환한다

② 쿼리(Query): 클라이언트가 데이터를 요청할 때 사용하는 문법

query {
  getUser(id: "1") {
    name
    age
  }
}

 

 

getUser(id: "1")을 요청하면 name과 age만 응답받는다

 

(응답 예시)

{
  "data": {
    "getUser": {
      "name": "Alice",
      "age": 25
    }
  }
}

③ 변이(Mutation): 데이터를 추가, 수정, 삭제할 때 사용

mutation {
  createUser(name: "Bob", age: 30) {
    id
    name
  }
}

 

(응답 예시)

{
  "data": {
    "createUser": {
      "id": "2",
      "name": "Bob"
    }
  }
}

④ 구독(Subscription): 실시간 데이터를 받을 때 사용

subscription {
  userAdded {
    id
    name
  }
}

 

새로운 사용자가 추가되면 자동으로 알림을 받을 수 있다

 

 

[GraphQL vs REST API]

REST API 에서 실시간 데이터 통신을 구현하려면 WebSocket을 사용해야 한다

 

[GraphQL을 지원하는 라이브러리]

• Java: GraphQL Java, DGS Framework
• JavaScript / Node.js: Apollo Server, Express-GraphQL
• Python: Graphene, Ariadne
• C# / .NET: GraphQL.NET
• Go: gqlgen

 

[GraphQL을 사용하는 상황 Best Practice]

✅ 필요한 데이터만 받아야 하는 경우 (모바일 앱, 네트워크 비용 절감)

✅ 관계형 데이터 요청이 많을 때 (ex: 사용자 정보 + 게시글 + 댓글)

✅ 단일 API로 다양한 클라이언트를 지원해야 할 때 (웹, 모바일, IoT)

✅ 실시간 업데이트가 필요한 경우 (WebSocket을 이용한 Subscription)

 

❌ GraphQL이 적합하지 않은 경우

• 단순한 API (CRUD만 필요한 경우 REST API가 더 쉬울 수 있음)
• 캐싱이 중요한 경우 (GraphQL은 REST API보다 캐싱이 어려움)
• 서버 부하가 많을 때 (GraphQL은 유연하지만, 복잡한 쿼리는 서버 성능을 저하시킬 수 있음)

 

 

 

GraphQL은 REST API의 단점을 보완하고, 클라이언트가 원하는 데이터를 효과적으로 요청할 수 있도록 도와주는 API 쿼리 언어이다. 특히 데이터 중복 요청이 많거나, 다양한 클라이언트를 지원해야 하는 서비스에서 강력한 성능을 발휘한다!