API 서버와 REST

API서버란?

• 앱/웹 서비스를 만드는 개발자들이 자주 이용하는 데이터 위주로만 응답을 하는 서버
• 즉 페이지 랜더링을 위한 HTML파일이 아니라 오로지 데이터만을 요구하는 경우, 그 데이터를 처리해서 응답해주는 서버를 의미함
• 주로 json형태의 응답형식을 사용하지만 필요에 따라 excel이나 html응답등이 필요함
• 시간이 지나도 호환성을 유지해야 한다는 부담감이 있을 수 있음
  • 유저층이 사용하는 앱의 버전이 다양함 > API서버도 버전에 따라 모두 응답이 가능하도록 버전의 개념이 필요
  • 참고)웹 서비스를 이용하는 유저는 항상 최신버전을 사용함. 응답으로써 html파일을 매번 받기 때문

 

REST(RESTful API)

• REST(Representational State Transfer) : 상태(state)를 나타내(representational) 보내준다(transfer)
• 웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고, URI로 표현된 리소스에 대한 행위를 HTTP Method로 정의하는 방식이며, 이러한 방식이 적용된 API통신을 RESTful API라고 한다.
• HTTP URI로 정의된 리소스를 대상(명사)에 HTTP method를 가한다(동사)라는 구조로 되어 있어 굉장히 깔끔하게 표현되며, 이처럼 존재자체가 (부연설명없이도) 그 구조를 직관적으로 드러낼 수 있다는 것이 restfulapi의 장점
• 반대로 단점도 존재한다. 바로 표준 규약이 존재하지 않는다는 점. 그냥 사람들간의 합의에 의한 것으로, 비효율적이거나 비생산적인 안티패턴도 흔하게 보인다
• 

 

다른 아키텍처와의 비교

• RestfulAPI는 시스템을 구현을 위한 여러 구조(혹은 아키텍쳐들 : GraphQL, SOAP, GRPC,REST...)중 가장 널리 사용되는 방식
• 추가적인 타입이나 기능의 설치 없이 그저 url을 통한 분기만 잘 만들어 주면 되기 때문에, 구현을 위해 소모되는 비용이나 시간이 매우 적다. 또한 실제로 배우기도 매우매우매우 쉬움
• 비교를 위해 GraphQL에 대해 이야기하자면, GraphQL은 하나의 url을 가지고 있고 그 URL에서 모든 메서드와 요청방식을 처리함 > 반대로 말하면 하나의 URL에서 모든 처리를 완수하기 위해 엄청나게 길고 복잡한 로직이 필요함 >> 신입개발자입장에서는, 혹은 뉴비입장에서는 새로 배우기 엄청어려움 

---

RESTful API 설계 규칙

• URL은 행위가 가해지는 대상인 리소스를 중의적이지 않고 명확하게 드러내야 한다. 따라서 URL은 오로지 명사로 표현되는 것이 바람직하다
  • /user/show/1 (X)
  • POST메서드 + /user/1 (O) : pk가 1인 user에 대해 db를 건드리는 작업을 하겠다!
  • customers/5/orders : 5번 고객의 모든 주문
  • orders/99/customer : 주문99번의 고객(주문한 사람)
• 또한 URL에서 특정 카테고리의 대상은 복수로 나타내는 게 일반적인 규칙이다. 물론 실제로는 케바케인 경우가 많다. 다만 일반적으로 옳은 방식은 복수를 사용하는 것임
  • POST메서드 + /users (O)
  • GET메서드 + /products/1 (O)
• HTTP method로는 일반적으로 GET, POST, PUT, DELETE를 사용하며, 대상인 리소스에 가해지는 행위를 의미
• /는 자원간이 계층관계를 타나낼 때 사용하며, uri의 마지막 문자로 /를 포함하지 않는다
  • django의 append_slash에 FALSE를 주는 이유도 마지막에 '/'를 자동 추가하는 경우를 방지하기 위함임
  • 계층관계라는 부분에 집중할 것. 정보는 '/users/{user_id}/profile'와 같은 식으로 나타난다.
• 불가피하게 URI가 길어지는 경우 -를 사용하여 가독성을 높인다. 반대로 _를 사용하지 않는다.
  • users/3/profile_image (X)
  • users/3/profile-image (O)

• 참고)HTTP프로토콜을 통한 API통신을 종종 REST API라고 부르는 경우가 있다. 그러나 반드시 REST아키텍처 스타일에 따라서 API통신이 이루어질 경우에만 REST API라고 부르는 것임. 대부분의 REST API는 실제로 REST아키텍처 스타일이 아닌 경우가 많다!

 

참고)HTTP method

• post : 생성
• get : 조회
• delete : 수정
• put : 대상 리소스 전체를 대체 > 멱등성(여러번 시도해도 동일한 결과)이 보장됨
• patch : 기존 리소스를 부분 대체. 요청 본문에 갱신할 리소스 정보를 제공 > 멱등성 미보장

 

요청/응답 형식 지정

• RESTful이라기 보다는 http에 있는 기능
• 요청메세지의 content-type헤더 메세지를 활용하여, 원하는 응답메세지의 형식을 넣을 수 있음
• 물론 서버단에서는 무시할 수 있으나(즉 강제성은 X), 일반적으로는 요청형식에 맞게 데이터를 잘 줌 
  •  ex)content-type : application/json , application/vnd.ms-excel, image/jpeg ....
  • 서버에서 해당 형식을 지원치 않으면 HTTP 상태코드 415(지원하지 않는 미디어 유형)을 반환하는 게 표준

 

STATUS CODE

• GET
  • 일반적으로 200ok
  • 리소스를 못찾으면 404(NOT FOUND)
• POST
  • 생성시 201(CREATED)응답. 새 리소스의 URI는 응답의 LOCATION헤더에 적어줌
  • 때로는 POST라 해도 새 리소스를 만들지 않을 수 있는데, 그때는 200응답
  • 잘못된 데이터로 요청시 400(잘못된 요청 응답). 
• Put
  • 기존 리소스의 업데이트가 성공적으로 이루어질 경우 200ok.
  • 상황에 따라 업데이트 할 수 없는 경우 409(리소스의 충돌)반환
• delete
  • 성공적으로 삭제시 204응답(반환할 내용이 없음)
  • 리소스가 애초에 없을 경우 404

 

 

ㅡㅡㅡㅡㅡ수정필요ㅡㅡㅡㅡㅡㅡ

Path parameter & Query parameter

• path parameter
  • 일반적인 url 경로를 통해 어떤 정보를 가져올지를 정하는 것

• 204 > 잘 삭제해서, 이제 기존 경로에 데이터가 없다고 말해주는 것임(즉 잘 처리되었음)

 

• Query parameter
  • filtering을 위한 기능
  • url에서 ?뒷 부분을 활용해 key/value형태로 데이터를 보낼 수 있음

• ordering이나 limit, offset등으로 받을 데이터의 양식을 규정할 수 있음

• search도 쓸 수 있음

 

• path parameter vs query parameter ?
  • 필터링, sorting, searching의 경우에 queryparameter를 사용하자!