REST API를 설계할 때 고려해야 할 사항

본 포스팅은 인프런 - Spring Boot를 이용한 RESTful Web Service 개발 강의를 바탕으로 공부하고 정리한 글입니다.

 

Richardson - Maturity Model

Richardson은 REST를 설계한 개발자이다.

Richarson이 말하는 Maturity Model이란 REST API를 개발할 때 확인해야 될 REST방식의 주요 요소들를 3가지 단계로 나눈 모델을 말한다.

 

LEVEL 0

• REST 방식으로 어플리케이션이 고려되었다기 보다, 기존의 resource를 웹서비스의 형태로 제공해서 단순히 URI만 매핑한 형태이다.
• 예시
  
  • http://server/getPosts 
  • http://server/deletePosts
  • http://server/doThis
  • 위 예시들을 보면 리소스에 어떠한 작업, 상태를 요청할 것인지 URI에 같이 표현하고 있다.

 

LEVEL 1

• 이 단계부터는 외부에 공개하고자 하는 resource 에 대해 의미있고 적절한 URI로 표현한다.
  하지만, resouce의 형태와 작업의 종류에 맞춰 적절한 HTTP 메소드를 지정하고 있지 않는 형태이다.
• 사용자 요청을 GET, POST만으로 처리하고 모든 반환 값을 ERROR 또는 200 OK라는 Status Code로 반환하는 단순한 형태이다.
• 예시
  • http://server/accounts
  • http://server/accounts/10
  • 위 예시들을 보면 일정한 패턴을 가지고 있지만 HTTP 메소드별로 서비스를 구분짓고 있지 않다.
  • 즉, URI는 적절하게 구분되어 있는 것 같지만 HTTP 메소드에 맞춰 상태 값을 요청하거나 처리하고 있지는 않은 단계이다. 

 

LEVEL 2

• LEVEL 1 단계에서 HTTP 메소드라는 기능을 추가한 형태이다.
• 제공하려는 resource 를 적절한 용도와 상태에 맞춰서 HTTP 메소드를 설계하고 서비스 하는 단계이다.

HTTP 메소드	resouce 상태
GET	resource의 상태가 변경되지 않음 단순히 읽기 전용
POST	새로운 resource 추가
PUT	기존의 resource의 상태를 변경
DELETE	resource를 삭제

• HTTP 메소드를 이용해 resource의 상태를 구분하여 서비스하게 되면 같은 URI라 하더라도 HTTP 메소드에 따라서 다른 상태와 서비스를 제공할 수 있게 된다.

 

LEVEL 3

• LEVEL 2단계에 HETEOAS라는 기능을 추가한 단계이다.
• resource에 접근한 상태라고 표현하기 위한 LEVEL 2단계에 추가해서 다음 작업으로 어떠한 것을 할 수 있는지,  또한 그 작업을 하기 위해서 다뤄져야 하는 resource URI는 어떤 것이 있는지 알려주는 기능을 포함하는 단계이다.
• 이러한 기능을 포함하면, 클라이언트 측에서 서버가 제공하는 서비스를 일일히 찾는 수고를 겪지 않아도 되며, 최소한의 진입점인 엔드포인트만을 가지고도 서버의 다음 URI 값을 알 수 있다.

 

 

RESTful Service를 설계할 때 고려해야 할 사항 정리

• 개발자 중심의 설계보다는 해당 API를 사용하는 소비자 입장에서 간단명료하고 직관적인 API 형태로 설계되어야 한다.
• REST API를 설계함에 있어 HTTP 메소드와 Request, Response의 타입, Header 값 등과 같이 HTTP 장점을 최대한 살려 설계해야 한다.
• Richarson의 Maturity Model에서 최소한 LEVEL 2 모델의 특징을 가지고 각 resource 별로 적절한 HTTP 메소드를 제공해야 한다.
• 각 API 요청에 따른 적절한 HTTP Status Code를 반환시켜줘야 한다.
• 제공하는 URI에는 사용자 비밀번호와 같이 중요한 데이터를 포함해서는 안된다.
• 제공하려는 모든 resource의 타입을 복수 형태로 표시해야 한다.
  • 단수형태의 URI가 아닌 복수형태의 URI를 사용해야 하며, 특정한 resource를 지칭하고 싶다면 다음 depth에 URI로 표현하것이 좋다.
    
  • /users        사용자 목록
  • /users/1    특정한 사용자 지칭
• resource에 대한 정보는 동사 형태가 아닌 명사 형태로 표현하는 것이 좋다.
  • 사용자 입장에서 명사형이 더욱 직관적일 수 있다.
  • 간단명료하게 어떤 서비스 어떤 resource를 제공하는 API인지 명시하기 위해서는 동사형보다는 명사형을 사용하는 것이 좋다.
• 일관된 접근 엔드포인트를 사용하는 것이 좋다.
  • PUT          /gists/{id}/star
  • DELETE   /gists/{id}/star
  • 하나의 URI 엔드포인트에서 HTTP 메소드에 따라 여러가지의 요청 처리가 될 수 있도록 하는 것이 좋다.