REST API vs GraphQL

 

API란 무엇인가?

Application Programming Interface의 약자로 기존에 있는 응용 프로그램을 통해서 데이터를 제공받거나 기능을 사용할 때 사용하는 인터페이스 및 규격을 말한다.

뭔 소리야…..

가장 대표적인 예시로 레스토랑 키오스크가 있다. 고객(내가 만드는 프로그램)이 키오스크(API)를 통해 주문을 한다. 키오스크는 내 주문 내역을 주방(API 제공자)에 제공한다. 주방에서 요리를 해 고객에게 음식을 가져다준다. 키오스크가 손님의 주문을 주방으로 전달하는 매개체(API) 역할을 하는 것이다.

REST란 무엇인가?

REST(REpresentational State Transfer)는 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고받는 모든 것을 의미한다.

HTTP URI(Uniform Resource Identifier)을 통하여 자원을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통하여 자원에 대한 행위를 정한다고 볼 수 있다.

EX) REST API

• GET /userIds/h0ng95
  • 위의 REST API의 예시를 보면 맨 앞에 GET이라는 것이 있다.
  • GET은 가져온다의 뜻을 가지고 있다 보니 조회를 할 경우에 사용한다.
  • 그리고 뒤에 /userIds/h0ng95은 userId들 중에서 h0ng95를 뜻한다.

즉 userId들 중 h0ng95를 조회하고 싶다는 의미를 가지게 된다.

이제 REST의 특징을 한번 살펴보고 본격적으로 REST API를 알아보도록 하자.

REST의 특징

• Server-Client (서버-클라이언트 구조)
  • 자원이 있는 쪽이 Server, 자원을 요청하는 쪽이 Client가 된다.
  • REST 서버가 API를 제공하는 방식이기에 클라이언트와 독립적으로 작동한다.
  • 서로 간의 의존성이 줄어들고 독립적 개발을 할 수 있다.
• Stateless (무상 태성)
  • Client의 context를 Server에 저장하지 않는다.
  • Server는 각각의 요청을 완전히 별개의 것으로 인식하기에 클라이언트를 고려하지 않고 구현할 수 있다.
• Cacheable (캐시 처리 가능)
  • REST는 HTTP 표준을 기반으로 만들어져 있기 때문에 HTTP의 강력한 특징인 캐싱을 사용할 수 있다.
  • Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능
  • 캐시 사용을 통해 응답 시간이 빨라지고 REST Server 트랜잭션이 발생하지 않기 때문에 전체 응답 시간, 성능, 서버의 자원 이용률을 향상할 수 있다.
• Layered System (계층형 구조)
  • 클라이언트는 최상위 계층이기에 REST API Server만 호출한다.
  • REST Server는 다중 계층으로 구성될 수 있다.
    • 서버단의 경우에는 로드밸런싱/암호화 및 Proxy 게이트웨이 등 중간 매체를 자유롭게 사용할 수 있다.
• Code-On-Demand (optional)
  • Server로부터 스크립트를 받아서 Client에서 실행한다(반드시 충족할 필요는 없다).
• Uniform Interface (인터페이스의 일관성)
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다(특정 언어나 기술에 종속되지 않는다.)

수많은 장점이 존재하기에 사실상 모두가 REST를 사용하고 있다. 하지만 단점과 한계도 분명 존재한다.

REST API란 무엇인가?

REST API란 REST 기반으로 API를 구현한 것을 이야기한다.

• REST는 HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 클라이언트, 서버를 구현할 수 있다.
• 즉, REST API를 제작하면 델파이 클라이언트뿐 아니라, 자바, C#, 웹 등을 이용해 클라이언트를 제작할 수 있다.
• REST API 설계 규칙이 있다(반드시 지킬 필욘 없지만 되도록 지키자!)

REST API 설계 기본 규칙

• URI는 리소스를 표현해야 한다.
  • URI에는 절대로 Method가 들어가면 안 된다.
  • 리소스 명은 동사가 아닌 명사를 사용하며 대문자를 사용하지 않는다.
  • 리소스는 Collection과 Document로 표현할 수 있다.
    • Collection은 DB의 테이블 정도로 생각할 수 있다. (무조건 복수형)
    • Document은 DB 테이블의 레코드로 생각할 수 있다. (단수형) ex GET /users/h0ng95
• 리소스에 대한 행위는 HTTP Method로 표현해야 한다.
  • GET은 리소스를 조회한다.
    • GET /users (user 목록 조회)
  • POST는 리소스를 생성한다.
    • POST /users(유저 정보 생성)
  • PUT은 리소스를 업데이트한다.
    • PUT /users/h0ng95 (h0ng95 유저 정보 전체 업데이트)
  • PATCH
    • Patch /users/h0ng95(h0ng95 유저 정보 부분 업데이트)
  • DELETE /users/h0ng95 (h0ng95 유저 정보 삭제)
    • DELETE는 리소스를 삭제한다.
• 요청에 대한 응답의 상태 코드도 명확하게 돌려줘야 한다.
  • 2xx : 성공 관련 응답
  • 3xx : 리다이렉션 관련 응답
  • 4xx : 클라이언트 에러 관련 응답
  • 5xx : 서버 관련 에러 응답

REST API 설계 규칙

• 슬래시 구분자는 계층 관계를 나타내는 데 사용한다.
  • 예시 /Users/userId
  • 그렇기 때문에 URI의 마지막 문자에는 슬래시(/)를 포함하지 않는다.
• 불가피하게 URI이 길어질 경우 하이픈(-)을 사용한다.
  • 언더바(_)는 상대적으로 보기 힘들거나 폰트에 따라서 문자에 가려지기에 사용하지 않는다.
• 파일 확장자는 URI에 포함하지 않는다.
  • 확장자가 필요할 경우 Accept header를 사용한다.
• 리소스 간에 연관 관계가 있는 경우에는 {}로 감싼다.
  • 예시 ) GET : /users/{userid}/devices

---

작업을 계속하다 보면 이 모든 것을 지키면서 개발하는 것은 어렵다. 하지만 지키지 않을 경우에는 복잡도가 상승하여 문제가 발생하게 된다.

이러한 것을 극복하기 위해서 나타난 GraphQL에 대해서 알아보고, 두 개의 차이점을 확인해보자.

Facebook에서 GraphQL을 만들게 된 계기

빠른 속도로 수많은 데이터를 주로 모바일 사용자가 많았던 페이스북에서는 앱의 복잡성이 늘어남에 따라서 REST API를 사용한 방식의 문제에 직면하게 됐다.

REST API에는 무슨 문제가 있었을까?

• 끝없는 엔드포인트가 일으킨 문제
  • 서비스가 확장될수록 엔드포인트가 늘어나게 되었고, 이것을 감당하는 것이 힘들어졌다.
  • 만약 엔드포인트가 변경이 되었을 경우 프론트 백엔드 모두 수정을 해야 한다.
• API Docs 최신화 및 버전 관리 문제
  • 백엔드가 API를 만들거나 변경될 경우 사용하는 방법을 적어놓은 API 명세를 관리해야 한다.
  • 관리가 되지 않을 경우 호환의 문제가 발생하여 작업이 front가 개발을 하는데 차질이 생길 수 있다.
• Over-Fetching의 문제
  • 불필요한 정보를 같이 받아오는 것을 Over-Fetching이라고 이야기한다.
  • REST API이 요청을 할 경우 모든 데이터를 받아오게 되는데 이러한 문제 때문에 수많은 요청이 있을 경우 성능 하락으로 이어진다.
• Under-Fetching의 문제
  • 요청을 한 것에 관련된 정보를 가져오기 위해 반복 호출을 하는 것을 Under-Fetching이라고 이야기한다.
  • REST API에서는 이것을 하기 위해서는 호출을 한 후 반복문을 돌려서 또다시 API 요청을 해야만 한다.

페이스북은 이러한 문제를 해결하기 위하여 GraphQL을 만들게 되었다.

GraphQL이란?

2012년도에 페이스북 개발자들이 개발하여 2015년에 공개적으로 발표한 쿼리 언어다. REST를 대체할 수 있고, 장점이 상당히 많아서 최근 사용자가 늘어나고 있는 추세다.

공식 홈페이지 : https://graphql-kr.github.io/

위의 REST API의 문제점을 개선하려고 노력한 것이 바로 그래프 큐엘이다.

어떤 식으로 해결이 되었는지 하나하나 짚어가면서 설명을 해보려고 한다.

단 한 개의 엔드포인트

수많은 엔드포인트로 나눠져 있던 것들은 한 개로 합쳐져서 편리하게 사용할 수 있게 되며 REST API의 GET은 Query로 POST PUT DELETE는 Mutation으로 두 가지로 사용할 수 있다.

3가지의 메서드가 Mutation으로 통합되다 보니 어떤 API인지 확인을 하기 위하여 API 앞단에 fetch, create, update, delete 뒤에 자원의 이름을 붙여서 사용하는 편이다.

Query라는 타입으로 모든 유저들을 조회하는 API의 코드

@Query(() => [User])
fetchUsers(){
	return this.userService.findAll();
}

Mutation이라는 타입으로 게시글을 생성하는 API의 코드

@Mutation(() => User)
createUser(
	@Args('createUserInput') createUserInput: CreateUserInput,
	){
	return this.userService.create({
		createUserInput,
	));
}

원하는 데이터만 골라서 받아올 수 있는 GraphQL

REST API를 통해서 인물의 정보를 받아오면 필요한 정보 이외에도 너무나 많은 정보까지 함께 받아야 하는 것과 달리 GraphQL은 쿼리 작성을 통해 필요한 데이터만 골라 받아올 수 있다..

GraphQL request

query {
    user(userID: 1) {
        name
        age
        phone
    }
}

GraphQL response

{
    "data": {
        "user": {
            "name": "hong",
            "age": 28,
            "phone": 01012341234,
        }
    }
}

GraphQL 장단점

이러한 특징들로 GraphQL이 REST API와 비교해서 가지는 장점은 다음과 같이 정리할 수 있다.

1. HTTP 요청 횟수를 줄일 수 있다. Restful의 경우 필요한 리소스 별로 요청해야 하고, 필요한 데이터들이 부분적으로 나눠서 개발되어 있다면 그만큼 요청 횟수가 늘어난다. 하지만 GraphQL은 원하는 정보를 하나의 쿼리에 모두 담아 요청할 수 있다.
2. **HTTP 응답 사이즈를 줄일 수 있다.**Restful의 경우 응답의 형태가 정해져 있기 때문에 필요한 정보만 부분적으로 요청하는 것이 힘들고, 자연스럽게 데이터의 사이즈가 클 수밖에 없다.  GraphQL을 사용함으로써 응답 데이터 사이즈를 최소화하여 특히 모바일 환경의 부담을 줄일 수 있다.
3. **프론트엔드와 백엔드 개발자의 부담을 덜 수 있다.**Restful API를 사용한다면 프론트엔드 개발자는 API의 request/response 형식에 의존하게 된다. 따라서 새로운 엔드포인트를 효율적이게 개발하기 위해서는 프론트엔드와 백엔드 개발자의 커뮤니케이션이 강제되는 경우가 많았다. 하지만 GraphQL은 request/response 의존도가 많이 없기 때문에, 개발자들의 API 개발 부담을 덜 수 있다.

GraphQL에도 단점은?

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