[http] REST API

software 아키텍처 - REST

REST - Representational State Transfer 는 정확히는 아키텍처 원리를 의미하는데,
아키텍처 원리는 '자원을 정의하고 자원에 대한 주소를 지정하는 것'을 말한다.
(REST 외에 SOAP, Graphql, GRPC 등이 있다)

프로젝트를 진행할 때 다양한 step이 존재하고, 어느 정도 API 구현이 완료되면 프론트와 논의하여 uri를 포함, headers, 상태코드 등을 작성하게 된다. 아래는 예시.

• https://www.google.com:443/search?q=hello&hl=ko
• https://fritz.co.kr/member/login
• 응답: 200,201,400,401,403,500 등의 status code

그런데 이런 정보들을 작성하는 것이 워낙 중구난방이었는지,
로이 필딩이란 사람이 처음 REST라는 아키텍처 원리를 논물을 통해 발표했다.
핵심은 "리소스와 리소스에 대한 행위(http method)를 구조적으로, 직관적으로 작성하라"는 것.

그래서 REST API는 아키텍처 원리이기도 하면서, 하나의 네트워킹 문화라고도 볼 수 있겠다. 이렇다보니 실제로는 개발자나 조직 입맛에 따라 바꿔서 사용하는 등 안티 패턴(실제 많이 사용되는 패턴이나 비효율적인 패턴)도 많다고 한다.

RESTful API 라는 것은...

"RESTful" 하다는 것은 REST 아키텍처에 적용되는 원칙들을 잘 준수했다는 의미다.

• 리소스를 식별할 수 있다
• 해당 리소스를 어떻게 조작해야 하는지에 대한 메타데이터를 포함한다
• 자기서술적 메세지여야 한다 (어떤 미디어 타입이고, 어떤 파서를 사용해야 하는지 바로 파악)
  

  products라는 리소스를 조회(GET)해달라는 것이고, 성공하면 서버는 status code : 200 ok를 반환한다

  
  

아래의 세부 규칙을 따르면 RESTful 한 API를 설계할 수 있다.
1. URL rules

• 마지막에는 /를 포함하지 않음
• _ 가 아니라 -(hash)를 사용
• 소문자만 사용
• 파일 확장자는 넣지 않는다 (e.g. photo.jpg -> uri에 넣는 것이 아니라, headers/accept를 통해 payload의 미디어 타입을 정해야 한다)
• 행위(동사)는 예외적으로만 사용
  • POST 등의 method를 사용할 때, 이를 정확히 표현하기 어려운 경우가 다수 있음
  • 이 때 동사 형태의 컨트롤 uri를 사용함
  • e.g.) http://api.test.com/posts/duplicate
• 리소스 사이에 연관관계가 있는 경우, 리소스/고유 id/연관된 리소스 순서로 표현
  • e.g.) GET /users/{id: 1}/profile
• 
  

2. HTTP headers

• content-location이 필요할 때 사용해야 한다
  • POST는 멱등하지 않으므로, 새로 생성되었음을 알 수 있는 content-location을 활용 (Content-location: /users/1, users/1에 새롭게 생성되었음)
• content-type은 applictaion/json으로 사용한다
  
  

3. HTTP methods

• GET/POST/PUT/DELETE는 반드시 포함하되, uri에는 포함하지 않는다
• OPTIONS/HEAD/PATCH를 활용해 완성도를 높인다
  • OPTIONS: 요청 가능한 http method를 알려줌
  • HEAD: 요청에 대한 header 정보만 응답함
  • PATCH: 일부 수정만 처리해줌
    
    

4. HTTP status

• 정확한 상태 코드를 전달한다 (ok면 200, 에러면 400 등)
  • 상태 코드만으로 어떤 상태인지 파악 가능해야 한다
  • 500 에러는 절대 사용자에게 보여주지 않는다 (서버에서 모든 에러 처리해야 함)
• 세부 사항은 응답 객체에 링크 형태 등으로 추가할 수 있다

HTTP/1.1 404 Not Found
{
    "code" : -765,
    "more_info" : "https://api.test.com/errors/-765"
}

• ordering (정렬)
  • order 를 사용 (GET /users?order=name)
• filtering (필터)
  • AND, OR, =, !=, >, <, IN, NOT IN, LIKE
  • 예시: type = ssd or (cpu=1 or memory>=2) and staus != 04
• field-seleting (일부 필트만 호출)
  • 예시: GET /users?fields=level
  • -를 붙이면 그 필드만 제외해서 호출 가능
    (예시: ?-fields=level, level 필드 제외하고 모두 반환)
  • 존재하는 필드가 하나도 없는 경우, 해당 요청 무시하고 모두 반환

❓ path parameter vs query parameter
1) products/3
2) products/?id=3
1번은 path parameter방식이고 2번은 query parameter 방식이다.
둘 다 제품 3번을 조회하는 것이라고 했을 때, 좀 더 RESTful한 것은 1번이다.
(필터링 등의 과정 없이 바로 3번만 조회하면 되기 때문)
query parameter는 filtering/sorting/searching에 더 적합하다.

Examples

몇 가지 예시 및 비교를 통해 최종 정리 !

1) http://10.58.4.1:8000/detail_page > http://10.58.4.1:8000/product 
2) http://10.58.4.1:8000/main_page > http://10.58.4.1:8000/products
3) http://10.58.4.1:8000/find/product > http://10.58.4.1:8000/product/
4) http://10.58.4.1:8000/add/product > http://10.58.4.1:8000/product
5) http://10.58.4.1:8000/product_reviews > http://10.58.4.1:8000/products/1/reviews
6) http://10.58.4.1:8000/product_filter > http://10.58.4.1:8000/products?name= 

참고 자료:
https://library.gabia.com/contents/8339/
https://ko.wikipedia.org/wiki/REST
https://medium.com/@fullsour/when-should-you-use-path-variable-and-query-parameter-a346790e8a6d