API 스타일 : REST vs GraphQL

REST + HTTP

REST API는 URL을 기반으로 통신한다. URL은 Uniform Resource Locator의 약어로, 필요로 하는 리소스의 주소를 나타낸다. 가령 nomadmovies.co/api/movies/1 이렇게 URL을 작성하면 nomadmovies.co의 리소스인 movies 중 1번을 의미한다.

 

리소스에 대한 동작은 HTTP의 메소드로 정의하는데, GET, POST, PUT, DELETE 등 리소스로 어떤 작업을 할지 구체적으로 넘겨준다. POST나 PUT 등 추가적으로 넘겨줄 데이터가 필요하다면 HTTP 패킷의 메시지 바디를 사용한다.

 

REST API 예시

• GET domain/users
• POST domain/products {”name”:”생강”,”price”:3000}
• DELETE products/1

 

REST API가 대중적인 이유는 무엇일까? 관례 덕분에 이해하기 쉽고, 조직화되어있고, 간단하고, 전세계의 거의 모든 디바이스들이 URL로 요청을 보낼 수 있다는 장점 때문이다.

 

REST API 규약

REST API 모범 사례 – REST 엔드포인트 설계 예시

REST API 모범 사례 – REST 엔드포인트 설계 예시

 

개인적인 궁금증, URL에 형용사를 사용해도 될까?

→ 가능하다! 중요한 것은 URL이 리소스를 명확하게 식별하는 것. 형용사를 사용하여 URL에 구체적인 의미를 부여하는 것은 REST 규약에 어긋나지 않는다. 예를 들어 특정 사용자가 차단한 사용자 목록을 불러오는 REST api는 다음과 같은 URL로 표현할 수 있다.

GET /users/{userId}/blocked

 

 

REST API의 단점

 

REST API는 미리 정해진 메시지를 기반으로 응답을 제공한다. 따라서 다음과 같은 문제점이 발생한다.

• over fetching : 클라이언트가 필요한 것보다 더 많은 데이터를 응답한다. 필요한 데이터만 제공한다면 응답 지연을 줄일 수 있는 여지가 있다.
• under fetching : 클라이언트가 필요한 것보다 적은 데이터를 응답한다. 추가적인 API 요청이 필요하다.

 

GraphQL은 정적인 응답만을 반환하는 방식 대신, 클라이언트가 필요로 하는 응답을 동적으로 구성할 수 있도록 더 유연하고 효율적인 API를 제공한다.

 

GraphQL이란?

GraphQL: API를 위한 쿼리 언어

GraphQL은 API를 위한 쿼리 언어이다.

 

GitHub - graphql/graphql-spec: GraphQL is a query language and execution engine tied to any backend service.

GraphQL은 하나의 아이디어이자 스펙이다. GraphQL은 API 요청을 메시지가 아닌 데이터 중심으로 구성하여, 클라이언트 입장에서 더 유연하고 효율적인 API를 제공한다.

 

Over Fetching

 

GraphQL이 해결하는 REST의 문제로 두 가지가 있는데, 첫번째는 over fetching이다.

 

클라이언트가 실제 사용할 데이터가 아니어도, 특정 요청에 대한 전체 데이터를 받는다. 필요한 것보다 더 많은 data를 fetch한다. 즉, 쓸데 없는 데이터를 받는다.

 

API 클라이언트는 3번 아이디를 가진 영화의 제목, 이미지 url, 평점 정보만 필요하다. 하지만 REST api를 사용하여 /movies/3을 요청하면 API 개발자가 정의해둔 3번 아이디를 가진 영화의 모든 상세정보를 끌어온다. API 클라이언트 입장에서는 데이터가 아닌 서버에 의존하므로, 서버가 API로 내려주는 데이터에 의존해야한다.

 

GraphQL은 서버가 내려주는 API가 아닌 서버의 데이터를 제어한다. 위의 상황에서 GraphQL을 사용하면 서버에게 3번 아이디를 가진 영화의 제목, 이미지 url, 평점 정보를 달라고 직접 요청하면 된다.

// 요청
{
  movie(id: "3") {
    name
    image_url
		ratings
  }
}

// 응답
{
	"data": {
	  "movie": {
	    "name": "바람과 함께 사라지다",
	    "image_url": "http://...",
			"ratings": 4.5
	  }
	}
}

 

 

Under Fetching

 

GraphQL이 해결하는 REST의 문제로 두 가지가 있는데, 두번째는 Under Fetching이다. Unfer Fetching은 우리가 필요한 것보다 덜 받는 문제이다.

 

api 응답으로 영화에 대한 상세정보를 받았고, 화면에 뿌려주려고 한다. 그런데 장르 정보를 보니 화면에 뿌려줄 장르 문자열이 아닌 식별자 정보가 들어있다. 그래서 화면에 장르 문자열까지 뿌려주려면 추가적인 요청이 필요하다.

 

하지만 GraphQL API는 한번의 요청으로 앱에 필요한 모든 데이터를 가져온다. 필요한 데이터가 무엇인지 schema를 직접 구성해서 전달하기 때문이다. 추가적인 요청이 필요하지 않으므로, GraphQL을 사용하는 앱은 느린 모바일 네트워크 연결에서도 빠르게 수행할 수 있다.

위의 영화 장르를 가져오는 GraphQL API는 다음과 같이 만들 수 있다.

// 요청
movie {
	// ..
	genres {
		name
	}
}

// 응답
{
	"data": {
		"movie": {
			// ..
			"genres": [
				{
					"name": "romance"
				},			
				{
					"name": "thriller"
				},
			]
		}
}