[이론] REST API / GraphQL

API(Application Programming Interface)

API는 다른 애플리케이션에서 접근하여 정보 또는 기능에 접근할 수 있도록 하는 인터페이스이다.

API Architecture style로는 RPC, SOAP, REST, GraphQL 등이 있다.
각 Architecture는 표준화된 데이터 교환 절차와 규격을 가지고 있다.

 

필자는 여러 API Architecture 중 REST와 GraphQL을 기준으로 포스팅 작성을 할 것이다.

REST와 GraphQL탄생 이유를 알기 위해, 이전에 사용되던 RPC, SOAP의 사용법과 단점을 간단하게 알아보자.

RPC

사용법

서버의 함수를 클라이언트 로컬의 함수처럼 호출하여 사용할 수 있음.

# 서버 코드 (Python)
def add(a, b):
    return a + b

# 클라이언트 코드
result = remote_call("add", [5, 10])
print(result)  # 서버의 add 함수가 호출되어 15를 반환

위와 같이 서버/클라이언트가 구성되어 지면, 네트워크 요청/응답은 아래와 같다. 

* 아래는, http 기반 통신을 할 때의 예제이고, rpc는 http외의 프로토콜을 이용해 통신할 수도 있다.

# 요청
POST /rpc HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "method": "add",
  "params": [5, 10]
}

# 응답
HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": 15
}

단점

• 플랫폼 종속적 : 클라이언트와 서버가 같은 언어를 사용해야 함. 서로 다른 언어일 경우, 추가 작업이 필요함.
• 유연성 부족 : 서버의 함수명이 바뀌면 클라이언트 코드도 바꾸어줘야 함.
• 방화벽 문제 : http 기반 통신이 아니라 다른 프로토콜을 이용할 경우, 특정 포트에 대한 방화벽 작업을 한 후에 이용 가능.

SOAP

사용법.은 따로 검색해 보시길.. 걍 복잡함..

단점

• 복잡성 : xml기반으로, 데이터 형식 복잡. 데이터량이 큼.
• 표준 요구: WSDL(Web Services Description Language)이라는 별도의 인터페이스 정의 언어를 사용해야 하며, 구현이 복잡.
• 성능 문제: 데이터 처리 속도가 느리고, 리소스를 많이 소비함.
• HTTP의 장점을 활용하지 못함: SOAP는 단순히 HTTP를 전송 프로토콜로 사용할 뿐, HTTP 메서드(GET, POST 등)나 상태 코드와 같은 특징을 사용하지 않음.

---

REST API

RPC와 SOAP의 단점들을 보완하여 탄생한 API Architecture Style 중 하나.

특징

• 리소스(데이터) 별 엔드 포인트 존재. /users/{id}/posts , /users/{id}/products 
  • 클라이언트는 서버에서 응답해주는 데이터를 그대로 가져가야 함. 즉, 주고받는 데이터 중 불필요 데이터가 포함되어 있을 수 있음.
• http 이용. http를 이용하게 됨으로써 아래와 같은 특징들을 가지게 됨.
  • 요청 header 설정을 통해 캐싱 가능.
  • Stateless함. 각 요청은 독립적이며, 요청마다 필요한 모든 정보를 넘겨야 함. 클라이언트 측의 상태를 유지하고 있을 필요 없음.
    • 서버의 부하 줄임.
  • CRUD 작업 구분은 http method를 이용함.
    • GET 조회
    • PUT 전체 수정
    • PATCH 일부 수정
    • POST 생성
    • DELETE 삭제
    • ...
• 실시간 데이터 적용 불가. 실시간 적용을 위해서는 별도 기술 적용 필요. websocket 등..

단점

• Over-fetching : 위에 특징에 적어둠. 불필요한 데이터를 주고받게 될 수 있음.
• Under-fetching  : 필요한 데이터를 가져오기 위해 여러번 요청을 해야 함. '/users', '/users/{id}/posts'
  
  • 과도한 네트워크 요청으로 이어질 수 있음.
• API 스키마 유연성 부족 : 새로운 데이터 요구 사항이 추가되면, 엔드포인트 수정 또는 추가가 되어야 함.

GraphQL

REST의 단점들을 보완하여 탄생한 API Architecture Style 중 하나.

특징

• 엔드포인트는 '/' 하나만 존재.
  • 필요 데이터는 클라이언트에서 지정 요청 가능. 즉, 불필요 데이터에 대해서 주고받을 필요 없음.
• http method는 POST만 이용.
  • body에 GraphQL 쿼리를 입력해야 하기 때문임.
  • http를 이용하기 때문에 rest api와 같이 stateless한 상태를 가지지만, 요청마다 다른 동적인 형태의 데이터 요청을 할 수 있음.
  • GraphQL은 데이터가 동적일 수 있다는 점에서, http를 이용함에도 불구하고 캐싱 작업은 제한적일 수 있음.
• GraphQL 쿼리 이용하여 CRUD 작업 요청.
  • R(조회) - body에 'query' 작성
  • 그 외 - body에 'mutation' 작성
• 실시간 데이터 처리 가능.
  
  • GraphQL 쿼리 중 body에 subscription을 작성하여 가능.

GraphQL은 REST와 HTTP의 철학에서 벗어나 클라이언트 중심의 데이터 페칭에 초점을 맞춘 아키텍처 스타일이다. HTTP의 기능을 잘 활용하지 못한다는 점이 단점이 될 수 있지만, 이를 통해 얻는 데이터 페칭의 유연성과 효율성이 더 큰 장점으로 작용할 수 있다.

• 한계: HTTP의 메서드와 상태 코드 활용 부족, 캐싱 제약.
• 장점: 필요한 데이터만 요청, 단일 엔드포인트, 유연한 쿼리 작성.