REST API vs SOAP API (with GraphQL)

한강섭·2025년 4월 7일

CS REST Soap VS graphql

웹 개발을 위한 VS 시리즈

목록 보기

9/19

썸네일 출처

API란? (Application Programming Interface)

어떤 서버의 특정한 부분에 접속해서 그 안에 있는 데이터와 서비스를 이용할 수 있게 해주는 소프트웨어 도구

API의 주요 기능

데이터 교환: 서로 다른 애플리케이션 간에 데이터를 주고받을 수 있습니다.
기능 호출: 다른 애플리케이션의 기능을 호출하여 사용할 수 있습니다.
서비스 통합: 여러 서비스를 하나의 애플리케이션에서 통합하여 제공할 수 있습니다.

REST

Representational State Transfer의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 의미

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고,
HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해
해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.

Create : 데이터 생성(POST)
Read : 데이터 조회(GET)
Update : 데이터 수정(PUT, PATCH)
Delete : 데이터 삭제(DELETE)

REST API

REST API는 인터넷 식별자(URI)와 HTTP 프로토콜을 기반으로 합니다. REST는 HTTP 프로토콜 덕분에 ‘단순함’이 핵심이라고 할 수 있습니다. 데이터 포맷으로는 브라우저 간 호환성이 좋은 제이슨(JSON)을 사용합니다.

특징

Server-Client(서버-클라이언트 구조)
Stateless(무상태)
Cacheable(캐시 처리 가능)
Layered System(계층화)
Uniform Interface(인터페이스 일관성)

REST 왜 사용하나?

HTTP 프로토콜 덕분에 간단함
클라이언트-서버 통신 및 아키텍처를 용이하게 한다.
단일 균일 인터페이스를 사용한다.
웹에 최적화되어 있다.
뛰어난 성능과 확장성

REST API 예시

요청

GET /users/123

응답

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "010-1234-5678"
}

SOAP

SOAP(Simple Object Access Protocol)는 그 자체로 프로토콜이며, 보안이나 메시지 전송 등에 있어서 REST보다 더 많은 표준들이 정해져있기 때문에 조금 더 복잡합니다.

더 높은 수준의 보안(예: 은행과 인터페이스하는 모바일 애플리케이션), 안정적인 통신이 필요한 메시징 앱, 레거시 시스템과의 통신또는 ACID 준수가 필요할 때 SOAP API를 사용한다!

SOAP API를 사용하는 이유

훨씬 더 엄격한 보안을 가지고 있음
안정적인 메시징 기능을 위한 성공/재시도 논리가 내장되어 있음
ACID 준수가 내장되어 있음 (금융 또는 기타 민감한 거래를 처리하기 좋음)

REST API VS SOAP API

SOAP는 프로토콜인 반면 REST는 아키텍처 스타일
REST API는 데이터 리소스(URI)에 엑세스 한다. SOAP API는 작업을 수행한다.
SOAP와 REST API 모두 HTTPS 및 SSL을 사용하여 통신을 암호화할 수 있지만 SOAP는 메시지의 전송 수준에서 더 우수하다.
SOAP는 더 많은 대역폭을 필요로 하는 반면, REST는 (API에 따라) 더 적은 리소스를 필요로 한다.
REST 호출은 캐시할 수 있지만 SOAP 기반 호출은 캐시할 수 없다.

SOAP API 예시

요청(XML)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://example.com/user">
   <soapenv:Header/>
   <soapenv:Body>
      <user:getUserInfo>
         <userId>123</userId>
      </user:getUserInfo>
   </soapenv:Body>
</soapenv:Envelope>

응답(XML)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <getUserInfoResponse>
         <name>Alice</name>
         <email>alice@example.com</email>
         <phone>010-1234-5678</phone>
      </getUserInfoResponse>
   </soap:Body>
</soap:Envelope>

결론1

웹 서비스용 API의 경우 SOAP 경로가 더 나은 선택이 아닌 한 RESTful 아키텍처로 하자!

그러나 보안에 대한 엔터프라이즈급 요구사항일때, 이미 SOAP를 사용하고 있는 레거시 시스템과 통합해야 할 때 SOAP가 선택될 수 있다!

GraphQL

GraphQL 은 API를 위한 쿼리 언어(Query Language)이며 타입 시스템을 사용하여 쿼리를 실행하는 서버사이드 런타임입니다. GraphQL은 특정한 데이터베이스나 특정한 스토리지 엔진과 관계되어 있지 않으며 기존 코드와 데이터에 의해 대체됩니다.

GraphQL vs REST

GraphQL이 REST와 비교해서 가지는 차이점은 크게 다음과 같다.

GraphQL은 보통 하나의 엔드포인트를 가진다.
GraphQL은 요청할 때 사용하는 쿼리에 따라 다른 응답을 받을 수 있다.
GraphQL은 원하는 데이터(response)만 받을 수 있다.

장단점 vs REST API

장점

HTTP 요청 횟수를 줄일 수 있다.
HTTP 응답 사이즈를 줄일 수 있다.
프론트엔드와 백엔드 개발자의 부담을 덜 수 있다.

단점

고정된 요청과 응답만 필요할 때에는 query로 인해 요청의 크기가 Restful보다 커질 수 있다.
캐싱이 REST보다 복잡하다.
파일 업로드 구현 방법이 정해져있지 않아 직접 구현해야 한다.

GraphQL 예시

요청

{
  user(id: 123) {
    name
    email
    phone
  }
}

응답

{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "phone": "010-1234-5678"
    }
  }
}

결론2

REST가 가지는 한계 때문에 개발된 GraphQL이지만, GraphQL이 완벽하게 REST를 대체 할 수는 없다.REST에 더 적합한 서비스에는 REST가 사용되는 것이 바람직하므로,
GraphQL과 REST의 장단점을 파악해 서비스에 맞는 방식을 고르는 것이 중요하다.