✔️ API 엔드포인트 아키텍처 패턴

API의 엔드포인트 구조를 구현하는 방식에도 널리 알려지고 사용되는 패턴들이 있다.

• REST 방식

  • 가장 널리 사용되는 API 엔드포인트 아키텍처 패턴이다.

• GraphQL

  • 페이스북이 개발, 비교적 최신 기술이다.

RESTful HTTP API

: REST(Representation State Transfer)ful HTTP API는 API 시스템을 구현하기 위한 아키텍처의 한 형식이다.

• API에서 전송하는 리소스를 URI로 표현하고 해당 리소스에 행하고자 하는 의도를 HTTP 메소드로 정의하는 방식이다.

• 각 엔드포인트는 처리하는 리소스를 표현하는 고유의 URI 주소를 가지고 있으며, 해당 리소스에 행할 수 있는 행위를 표현하는 HTTP 메소드를 처리할 수 있게 된다.

  • 사용자 정보를 리턴하는 "/users"라는 엔드포인트에서 사용자 정보를 받아오는 HTTP 요청은 다음과 같다.

  HTTP GET /users
  GET /users

  • 새로운 사용자를 생성하는 엔드포인트는 URI를 "/users"로 정하고 HTTP 요청은 다음과 같이 표현할 수 있다.

  POST /user
  {
    "name"  : "Paul"
    "email" : "ssm2319@gmail.com"
  }

이러한 구조로 설계된 API를 RESTful API라고 한다.
가장 큰 장점은
엔드포인트의 구조만 보더라도 해당 엔드포인트가 제공하는 리소스와 기능을 파악할 수 있다.
즉 구조의 직관성을 올려주는 자기 설명력(self-descriptiveness)이 강하다.

GraphQL

: 엔드포인트가 하나이며, 엔드포인트에 클라이언트가 필요한 것을 정의해서 요청하는 방식이다.

• RESTful 방식은 클라이언트들이 API가 엔드포인트들을 통해 구현해놓은 틀에 맞추어 사용해야 하다 보니 그 틀에서 벗어나는 사용은 어려워지기 때문에 GraphQL의 방식이 등장하게 되었다.

아이디가 1인 사용자의 정보와 그의 친구들의 이름 정보를 API로부터 받아 와야 한다고 생각해보면 일반적인 REST 방식의 API에서는 다음과 같이 두 번의 HTTP 요청을 보내야 한다.

GET /users/1
GET /users/1/friends

이 요청을 한 번의 HTTP 요청으로 줄이기 위해서는 다음과 같은 요청을 보내야한다.

GET /users/1?include=friends.name

둘 다 불필요하게 복잡하다.
만일 사용자 정보들 중 전부 필요하지 않고 이름 혹은 이메일도 필요하다면 HTTP 요청은 더욱 복잡해지게 된다.
GraphQL을 사용하면 다음과 같이 HTTP 요청을 보내면 된다.

POST /graphql

{
  user(id: 1) {
    name
    age
    friends {
      name
    }
  }
}

만일 사용자 정보는 이름만 필요하고, 대신 친구들의 이름과 이메일이 필요하다면 다음과 같이 보낸다.

POST /graphql

{
  user(id: 1) {
    name
    friends {
      name
      email
    }
  }
}

📌 GraphQL은 최신 기술이므로 널리 사용되고 있지는 않다.
그래서 백엔드 입문자에게는 REST 방식의 API를 이해하고 익숙해지는 것이 더 적합하다.