1.10.2 Restful API

프로젝트를 시작할 때 API에 대한 잘못된 개념 때문에 API를 자원단위가 아닌 페이지단위로 나누어 설계하게 되었다. 또한 마감기한에 쫒기면서 개발을 하다보니 그때그때 필요한 API들을 임시방편으로 만들게 되었다. 그 결과 Django REST framework를 가지고 RESTful하지 못한 API를 만들어버렸다.

그래서 이 프로젝트를 리팩토링하거나 다른 프로젝트를 진행할 때에는 같은 실수를 범하지 않기 위해서 REST API에 대한 내용을 아래에 정리하였다.

REST API

REST API란 Representational State Transfer의 약자로 웹의 장점을 최대한 활용할 수 있도록 만들 아키텍쳐이다.

REST의 특징은 다음과 같다.

• Uniform Interface : 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다
• Stateless : 상태정보를 저장하고 관리하지 않아 단순 요청만 처리한다
• Cacheable : HTTP웹 표준을 따르기 때문에 캐싱이 가능하다
• 자체 표현 구조 : REST API메시지만 보고도 쉽게 이해할 수 있다
• Client-server구조 : 서버와 클라이언트의 역할이 구분된다
• 계층형 구조 : REST서버는 다중 계층으로 구성될 수 있다

REST API를 설계할 때 가장 중요한 항목은 다음과 같다.

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

   GET /members/1 : 1번 멤버를 조회
   DELETE /members/1 : 1번 멤버를 삭제
   잘못된 예 : GET /members/delete/1

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다

   GET /members/1 : 1번 멤버를 조회
   잘못된 예 : GET /members/show/1

위와 같이 URI는 자원을 표현하는것에 집중하고, 행위에 대한 정의는 HTTP Method를 통해 표현한다.

URI가 자원을 잘 표현하기 위해서는 아래와 같은 규칙을 따라야 한다.

• / 는 계층관계를 나타내는데 사용하고 URI의 마지막문자로는 사용하지 않는다
• 하이픈(-)을 사용해 가독성을 높이고 밑줄(_)은 사용하지 않는다
• URI경로에는 영어 소문자를 사용한다
• 파일 확장자는 URI에 포함시키지 않는다
• 리소스간의 연관관계는 아래와 같은 방법으로 표현한다

  /리소스명/리소스ID/관계가 있는 다른 리소스명
  ex1) GET : /users/{userid}/devices
  ex2) GET : /users/{userid}/likes/devices

• Collection과 Document를 표현한다
  • Collection : Document들의 집합. 복수형
  • Document : 하나의 문서, 객체. 단수형

    ex) GET : sports/soccer/players/13
    => sports,players : Collection / soccer, 13 : Document 

마지막으로 REST API를 잘 설계하기 위해서는 각 리소스에 대한 응답을 제대로 보내주어야 한다. 이를 위해 HTTP 상태코드의 종류를 알고 상황에 맞는 상태코드를 보내주는 것이 중요하다. HTTP 상태코드는 크게 5가지로 나뉘고, 각각에 대해 세분화되어있다.

• 100번대(정보) : 요청을 받았으며 프로세스를 계속 진행함. 최근에는 거의 사용하지 않음

• 200번대(성공) : 요청을 성공적으로 받았으며 인식했고 수용함

  상태코드	메세지	설명
  200	OK	요청을 정상적으로 처리함
  201	Created	요청을 정상적으로 처리하고 새로운 리소스를 생성함(POST, PUT등)
  202	Accepted	요청을 수신하였지만 아직 처리하지 않음
  204	No Content	요청을 정상적으로 처리했지만 제공할 컨텐츠는 없음

• 300번대(리다이렉션) : 요청 완료를 위해 추가 작업 조치가 필요함

  상태코드	메세지	설명
  301	Moved Permanetly	요청한 리소스의 URI가 영구적으로 변경됨
  302	Found	요청한 리소스의 URI가 일시적으로 변경됨
  303	See other	요청한 리소스를 다른 URI에서 GET요청을 통해 얻어야 함
  304	Not Modified	캐시목적으로 사용됨. 클라이언트에게 응답이 수정되지 않았음을 알려줌
  307	Temporary Redirect	요청한 리소스가 일시적으로 변경되었고, 이전과 동일한 메소드를 사용하여 요청해야 함
  308	Permanent Redirect	요청한 리소스가 영구적으로 변경되었도, 이전과 동일한 메소드를 사용하여 요청해야 함

• 400번대(클라이언트 오류) : 요청의 문법이 잘못되었거나 요청을 처리할 수 없음

  상태코드	메세지	설명
  400	Bad Request	요청구문 또는 메세지등의 오류가 있어 서버가 요청을 이해하지 못함
  401	Unauthorized	리소스에 접근하기 위해 인증이 필요함
  403	Forbidden	클라이언트가 리소스에 접근할 권한이 없음
  404	Not Found	요청받은 리소스를 찾을 수 없음
  409	Conflict	요청이 현재 서버상태와 충돌함

• 500번대(서버 오류) : 서버가 명백히 유효한 요청에 대해 충족을 실패함

  상태코드	메세지	설명
  500	Internal Server Error	서버에 문제가 있음
  503	Service Unavailable	서버가 요청을 처리할 준비가 되지 않음

위에서 소개한 상태코드 외에도 여러 종류의 상태코드가 있지만 자주 사용되는 것들만 정리하였다.