[CS] REST API 바로 알기

[사족]

내가 원래 공부하던 Android와 전혀 다른 업무를 보는..회사에 입사한 이후 이직을 준비하고자 다시 Android 공부를 하기로 결심했고, 공부를 다시 시작하다보니 대학생 때 내가 얼마나 허술하게 공부했는지 깨달았다 (ㅠㅠㅠ) 현 블로그에 쓴 여러 글 들 중 기억이 하나도 안나는걸 보면 역시 공부는 끊임없이 반복하고, 기록하고 이해하여 내걸로 만드는게 왕도의 길인 것 같다.

아무튼 Android Retrofit2에 대해 공부하다가 HTTP, REST API 부터 제대로 개념을 짚고 가는게 맞을 듯 하여 블로그 등을 정독하고 정리해보았다. ( https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html 님 글이 정말 정말 정리가 잘 되어 있어서 대부분 내용은 이 분거를 참고하였다.)

REST API

1. 정의

(1) 간단한 정의

• REST 아키텍처의 제약 조건을 준수하는 어플리케이션 프로그래밍 인터페이스, REST는 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나

• => REST는 웹의 기존 기술과 HTTP를 그대로 활용하기에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일임

• “Representational State Transfer” 의 약자로, 자원을 이름으로 구분해 자원의 상태를 주고 받는 모든 것을 의미함

  • 자원: 문서, 그림, 데이터와 같이 해당 SW가 관리하는 모든 것
  • 자원의 표현: 예로 DB의 학생 데이터가 자원이라면, 이를 students라는 이름으로 자원을 표현함

  상태 전달?

  • 데이터가 요청되는 시점에서의 상태를 전달함 (JSON 혹은 XML을 이용해 데이터를 주고 받는 것이 일반적임)

• 자원?

(2) 구체적 정의

• HTTP URI를 통해 자원을 명시하고, HTTP Method (GET, POST, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것=> CRUD Operation:
  1. Create: 생성, POST 사용
  2. Read: 조회, GET 사용
  3. Update: 수정, PUT 사용
  4. Delete: 삭제, DELETE 사용
• => HTTP URI: 웹 사이트의 이미지, 텍스트, DB 데이터 등 모든 자원에 부여되는 고유한 ID

(3) REST가 필요한 이유

• 최근 서버는 다양한 브라우저, 안드로이드, IOS와 같은 모바일 디바이스처럼 다양한 클라이언트에서도 통신할 수 있어야 함. 이러한 멀티 플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처 중 REST가 필수적

2. REST 구성 요소

1. 자원: URI
   • 모든 자원에는 고유한 ID가 존재하며, 이 자원은 Server에 존재함
   • 자원을 구별하는 ID는 '/groups/:group_id' 와 같은 HTTP URI임
   • Client는 이 URI를 통해 자원을 지정하고, 해당 자원에 대한 상태 처리를 Server에 Request함
2. 행위: HTTP Method
   • GET, POST, PUT, DELETE 와 같은 HTTP Method를 통해 자원을 처리함
3. 표현: JSON, XML 등..
   • Client가 자원의 상태에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보냄
   • => Representation: REST에서 자원 하나는 JSON, XML, RSS 등 여러 형태로 나타낼 수 있으며 일반적으로 JSON, XML 을 사용함

3. REST 특징

1. Uniform
   • Uniform Interface는 URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 Interface로 수행하는 아키텍처 스타일을 의미
2. Stateless
   • 작업을 위한 state 정보를 따로 저장하고 관리하지 않음따라서 서버의 자유도가 높아지고 서버에 불필요한 정보를 저장, 관리하지 않아 구현이 단순해짐
   • => 즉, 세션 정보나 쿠키를 별도로 저장, 관리하지 않으므로 API 서버는 Request만 처리하면 됨,
3. Cacheable
   • REST의 가장 큰 특징은 HTTP 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 대부분 활용 가능함. 따라서 HTTP가 가진 Cache 기능이 적용 가능함. HTTP 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능함
4. Self-descriptiveness
   • REST API 메시지만 보고도 쉽게 이해할 수 있는 자체 표현 구조로 되어 있음
5. Client - Server 구조
   • REST Server는 API를 제공, Client는 사용자 인증이나 context (세션, 로그인 정보)를 직접 관리하는 구조로 분리되어 서로간 의존성이 줄어듦
6. 계층형 구조
   • REST Server는 다중 계층으로 구성될 수 있으며, Proxy, Gateway와 같은 네트워크 기반의 중간매체를 사용할 수 있게 함

4. REST API란

• 정의

  • REST 기반으로 서비스 API를 구현한 것

• 설계 기본 규칙

  • 용어
    • document: 객체 인스턴스 혹은 DB 레코드와 유사한 개념
    • collection: Server에서 관리하는 Directory 라는 Resource (document의 집합)
    • store: Client에서 관리하는 Resource 저장소
  1. URI 는 정보의 자원을 표현해야 함
     1. Resource는 동사보다는 명사로, 대문자보다는 소문자로 표현
     2. Resource의 document는 단수 명사
     3. Resource의 collecion은 복수 명사
     4. Resource의 store는 복수 명사
     5. => 예: GET /Member/1 (X) GET /members/1 (O)
  2. 자원에 대한 행위는 HTTP Method로 표현함
     1. URI에는 HTTP Method가 들어가지 않는다.
     2. URI에는 동사표현을 쓰지 않는다.
     3. 경로 부분 중 변하는 부분은 유일한 값, 즉 id로 대체한다.
     4. => 예: student 12번을 삭제할 경우 : DELETE /students/12
  3. 슬래시 구분자는 계층 관계를 나타내는데 사용함
  4. URI 마지막 문자로 슬래시를 포함하지 않음
  5. 하이픈은 URI가 긴 경로일 경우, 가독성을 높이는 데 씀
  6. 밑줄 _ 은 URI에 사용하지 않음
  7. URI 경로에는 대문자를 피하고, 소문자가 적합 (URI 스키마와 호스트 제외 나머지는 대소문자가 구별되므로)
  8. 파일 확장자는 URI에 포함하지 않음 (확장자는 accept header를 사용)
  9. 예:
     /members/12/photo.jpg (X)
     GET /members/12/photo HTTP 1.1 Host: restapi.example.com Accept: image/jpg (O)
  10. Resource 간에는 연관 관계가 있는 경우 /리소스명/리소스ID/관계가 있는 다른 리소스명 으로 표현
      (예: /users/{userid}/devices (일반적으로 has 관계를 표현 시))
  11. (예: /users/{userid}/likes/devices (관계가 애매하거나 구체적 표현이 필요 시))

• 설계 예시

• 

• Response Status Code

  • 1xx: 전송 프로토콜 수준의 정보 교환
  • 2xx: Client의 Request 성공적으로 수행 됨
  • 3xx: Redirect (Client가 Request를 완료하기 위해 추가적으로 행동을 더해야 함)
  • 4xx: Client Bad Request
  • 5xx: Server error

5. RESTful 이란

• 정의
  • REST 원리를 따르는 시스템을 지칭하는 용어로, REST API를 제공하는 서비스를 RESTful하다 할 수 있음
  • => 일반적으로 REST 아키텍처를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어
• 목적
  • RESTful은 성능 향상이 아니라 일관적인 컨벤션을 통해 사람의 이해도를 높이는 것이 주 목적
  • => 즉, 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것이 목표
• RESTful 하지 못한 경우
  1. 예: CRUD를 모두 POST Method로 수행하는 API
  2. 예: route에 resource, id 외의 정보가 들어가는 경우 (예: students/updateName)

Reference

https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html

https://meetup.toast.com/posts/92