API

• Application Programming Interface
  • 소프트웨어 애플리케이션 간에 서로 소통하기 위한 규약/인터페이스.
  • 소프트웨어 구성 요소 간의 상호작용을 도와주는 도구.
  • API를 통해 한 애플리케이션이 다른 애플리케이션의 기능과 데이터를 활용할 수 있음.

REST

• REpresentational State Transfer
  • 웹 기반 애플리케이션에서 자주 사용되는 소프트웨어 아키텍처 스타일.

RESTful API

• REST 원칙을 따르는 API.
• 네트워크 상에서 자원(데이터)을 표현/조작을 위한 표준화된 방법을 제공함.

특징

1. Uniform Interface
   • URI(Uniform Resource Identifier)로 지정한 자원에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일.
2. Stateless
   • 서버가 클라이언트의 상태를 유지하지 않음.
   • 클라이언트의 각 요청은 서버에 대한 완전한 정보를 포함해야 하며, 서버는 이전 요청의 상태를 기억하지 않고(세션, 쿠키 저장 x) 독립적으로 처리함.
   • 구현이 단순함.
3. Cacheable
   • HTTP를 사용하기 때문에 캐싱이 가능함.
   • Last-Modified 태그, E-Tag를 이용하여 캐싱을 구현할 수 있음.
4. Self-descriptiveness
   • REST API 메세지만 보고도 쉽게 이해할 수 있는 '자체 표현 구조'로 되어있음.
5. Client-Server Structure
   • 클라이언트와 서버의 역할이 확실히 구분되기 때문에 각각에서의 개발해야 하는 내용이 명확해지고 서로간 의존성이 줄어듬.
6. Layered Structure
   • 다중 계층으로 구성할 수 있으며 클라이언트와 서버 사이에 중간 계층을 추가하여 시스템의 유연성, 확장성을 향상시킬 수 있음.
   • 보안, 로드 밸런싱, 캐싱, 인증 등 다양한 기능을 수행하는 중간 계층.

REST API 디자인 가이드

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP 메서드로 표현한다.

REST API의 중심 규칙

1. URI는 정보의 자원을 표현해야 한다.

좋은 예) GET /members/1
안좋은 예) GET /members/delete/1 (행위에 대한 표현 포함 x)

2. 자원에 대한 행위는 HTTP 메서드로 표현한다.
   • POST: 자원 생성
   • GET: 자원 조회
   • PUT: 자원 수정
   • DELETE: 자원 삭제

안좋은 예) GET /members/delete/1 (행위에 대한 표현 포함 x, 적절한 메서드 사용)
좋은 예) DELETE /members/1

URI 설계 시 주의할 점

1. '/'는 계층 관계를 나타내는 데 사용한다.
2. URI 마지막 문자로 '/'를 포함하지 않는다.
   • 혼동을 주지 않기 위해
3. 가독성을 높이기 위해 '-'를 사용한다.
4. 밑줄(_)은 사용하지 않는다.
5. 소문자만 사용한다.
6. 파일 확장자는 포함시키지 않는다.

GraphQL

• API를 위한 쿼리 언어이며 타입 시스템을 활용하여 쿼리를 실행하는 서버사이드 런타임.

REST와의 차이점

1. 하나의 엔드포인트(Root endpoint)를 가진다.

   • 하나의 엔드포인트를 사용하여 요청하는 쿼리에 따라 다른 응답을 반환하는 방식.
   • 엔드포인트가 많을 경우 관리도 힘들고 많은 엔드포인트의 노출을 막기 위해 추가적인 처리가 필요할 수 있는데 GraphQL을 사용하여 이 문제들을 해결할 수 있다.

   // REST API
   // 전체 반의 정보
   example.com/class
   // 1반의 정보
   example.com/class/1
   // 1반의 전체 학생 정보
   example.com/class/1/students
   // 1반의 1번 학생 정보
   example.com/class/1/students/1
   
   // GraphQL
   // 하나의 엔드포인트에 다른 쿼리를 사용해 요청
   example.com/graphql

2. 원하는 응답 값만 골라서 받아올 수 있다.

   • 쿼리를 작성하여 엔드포인트에서 원하는 데이터만 골라서 받아올 수 있다.

   // REST API
   GET, https://swapi.dev/api/people/1
   
   // REST API response
   {
     "name": "Luke Skywalker",
     "height": "172",
     "mass": "77",
     "hair_color": "blond",
     "skin_color": "fair",
     "eye_color": "blue",
     "birth_year": "19BBY",
     "gender": "male",
     "homeworld": "http://swapi.dev/api/planets/1/",
     "films": ["http://swapi.dev/api/films/1/", "http://swapi.dev/api/films/2/", "http://swapi.dev/api/films/3/", "http://swapi.dev/api/films/6/"],
     "species": [],
     "vehicles": ["http://swapi.dev/api/vehicles/14/", "http://swapi.dev/api/vehicles/30/"],
     "starships": ["http://swapi.dev/api/starships/12/", "http://swapi.dev/api/starships/22/"],
     "created": "2014-12-09T13:50:51.644000Z",
     "edited": "2014-12-20T21:17:56.891000Z",
     "url": "http://swapi.dev/api/people/1/"
   }

   • REST API로 인물의 정보를 받아오면 전체 데이터를 받아와야 한다. 만약 이름, 키, 몸무게만 필요하다고 했을 때 GraphQL API를 사용하면 다음과 같이 요청할 수 있다.

   // GraphQL request
   query {
     person(personID: 1) {
       name
       height
       mass
     }
   }
   // GraphQL response
   {
     "data": {
       "person": {
         "name": "Luke Skywalker",
         "height": 172,
         "mass": 77
       }
     }
   }

장점

1. HTTP 요청 횟수를 줄일 수 있다.
   • 필요한 자원 별로 요청을 보내야 하는 RESTful API와 다르게 하나의 쿼리에 원하는 정보를 모두 담아 요청을 보낼 수 있다.
2. HTTP 응답 사이즈를 줄일 수 있다.
   • RESTful API는 응답 형태가 고정적이지만 GraphQL API는 원하는 데이터를 쿼리로 보내 응답 사이즈를 줄일 수 있다.

단점

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

Reference

[간단정리] GraphQL이란? (REST api와 차이점)
REST API 대신 ‘그래프QL’ 선택 전에... 알아야 할 장단점 5가지