REST API

• REpresentational State Transfer의 약자로 웹상의 여러 리소스(이미지, 동영상, 데이터)에 고유한 URI를 부여해 자원에 대한 주소를 지정(HTTP Method)하는 방법론, 규칙을 의미한다.
• API 시스템을 구현하기 위한 아키텍쳐 중 가장 널리 사용되는 형식 (Graphql, GRPC, REST..)
  => RESTful API는 REST 특징을 지키면서 API를 제공한다는 의미이다.
  결국, HTTP 요청을 보낼 때 어떤 URI, 어떤 HTTP method를 사용할 것인가에 대한 약속
  
  장점: self-descriptiveness, 지정된 형식이 있어 요청 자체만으로 API 목적이 쉽게 이해된다.
  단점: 표준규약이 없어 안티패턴(*실제 많이 사용되는 패턴이지만 비효율적이거나 비생산적인 패턴)으로 작성되는 경우가 흔하다.

기본 배경 지식

URI(Uniform Resource Identifier)

• 해당 사이트의 특정 자원의 위치를 구조와 함께 나타내는 유일한 주소
• https://finace.naver.com/login에서 'https:// ~ com'은 URL, /login은 URI다.
  HTTP Method
• HTTP request가 의도하는 action(GET, POST, DELETE, PUT)을 정의한 것
  Payload
• HTTP request에서 server로 보내는 데이터 (body)

RESTful API

• 웹 데이터 전송 방식 중 하나로 API의 엔드포인트 구조를 구현하는 방식이다.
• API에서 전송하는 자원(resource)을 URI로, 각 자원의 행위를 HTTP method로 정의한다.
• 엔드포인트는 리소스를 표현하는 고유한 URI를 갖고, 해당 리소스의 행위를 표현하는 HTTP method를 처리할 수 있게 한다.
  
• Method와 Resource 정보를 protocol과 host에 URI로 담아 request하면, 엔드포인트에 따라 해당 정보를 Reponse로 받아온다.
  ⚠️ 사용자가 주소창에서 보는 실제 URL이 아닌 클라이언트의 프론트엔드 개발자가 백엔드개발자에게 기능을 요청할 때 보내는 주소! 페이지 단위가 아닌 기능 단위로 구성됨을 유의!

설계 규칙

• URI 정보를 명확하게 표현한다. resource는 명사를 사용한다.
  GET/user/1 -> GET/users/1
• resource에 대한 행위를 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
  URI에 method를 포함하지 않는다. GET delete/user/1 -> DELETE/users/1
  URI에 동사를 포함하지 않는다. GET/user/show/1 -> GET/users/1, POST insert/user/2 -> POST/users/2
• resource 간 관계가 있는 경우 '/'로 표현한다. /리소스/고유ID/관계 리소스 GET /users/{user_id}/profile
• 파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다. GET user/1/profile-photo.jpg(x) -> GET user/1/profile-photo (이때, payload의 포맷은 headers에 accept 사용)
• URI는 / 구분자를 사용해 자원의 계층 관계를 나타낸다. 따라서 마지막 문자로 /를 포함하지 않는다.
• URI가 길어지는 경우 -을 사용해 가독성을 높인다. '_', '대문자'는 사용하지 않는다.

---

REST API 통신

• 상황에 따라 Query parameters (GET parameters), Path parameters로 통신할 수 있다.

Path parameters

• End-point에 경로를 지정하여 요청하는 방식
• GET Method
  
• POST, PATCH Method
  
• DELETE Method
  

Query parameter

• End-point에 query문으로 요청하는 방식
• 데이터를 조건으로 거르거나(filtering), 특정 방식으로 정렬하거나(ordering), 검색(searching) 등 조건에 맞추어 정제된 결과물을 얻을 수 있다.
  
• 신상품순(-id), 가격순 등 필터링에 사용할 수 있다.
  
  

Path parameters vs Query parameter

• Path parameter에 비해 Query parameter는
  조금 더 정제된 정보 Filtering, Sorting, Searching, Pagination를 가져올 때 쓴다.
• 검색 데이터가 없을 경우, Path parameter는 오류를 출력하고, Query parameter는 빈 페이지를 보여준다.