REST API 설계 규칙

REST(Representational State Transfer)는 Software Architecture의 한 형식이다.

이 용어는 Roy Fielding의 2000년 박사학위 논문에서 소개되었다. 

 

REST 아키텍처에 적용되는 6가지 제한 조건

1. 인터페이스 일관성(Uniform Interface) : 일관된 인터페이스로 분리되어야 한다.
2. 무상태(Stateless) : 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되어서는 안된다.
3. 캐시 처리 가능(Cacheable) : www에서와 같이 클라이언트는 응답을 캐싱할 수 있어야 한다.
4. 계층화(Layered System) 
5. Client/Server 구조 : 아키텍처를 단순화시키고 작은 단위로 분리(decouple)함으로써 클라이언트-서버의 각 파트가 독립적으로 개선될 수 있도록 해준다.
6. Code on demand(optional)

 

REST 인터페이스의 원칙에 대한 가이드

자원의 식별

요청내에 기술된 개별 자원을 식별할 수 있어야 한다. 웹 기반의 REST 시스템에서의 URI의 사용을 예로 들 수 있다. 예를 들어, 서버는 데이터 베이스 내부의 자료를 직접 전송하는 대신, 데이터베이스 레코드를 HTML,XML이나 JSON 등의 형식으로 전송한다.

메시지를 통한 리소스의 조작

클라이언트가 어떤 자원을 지칭하는 메시지와 특정 메타데이터만 가지고 있다면 이것으로 서버상의 해당 자원을 변경/삭제할 수 있는 충분한 정보를 가지고 있는 것이다.

자기서술적 메시지(Self-descriptiveness)

각 메시지는 자신을 어떻게 처리해야 하는지에 대한 충분한 정보를 포함해야한다. 예를 들어, MIME type과 같은 인터넷 미디어 타입을 전달한다면, 그 메시지에는 어떤 parser를 이용해야 하는지에 대한 정보도 포함해야한다. 미디어 타입만 가지고도, 클라이언트는 어떻게 그 내용을 처리해야할 지 알 수 있어야 한다. 메시지를 이해하기 위해 그 내용까지 살펴봐야 한다면, 그 메시지는 자기서술적이 아니다. 예를 들어, 단순히 "application/xml"이라는 미디어 타입은, 실제 내용을 다운로드 받지 않으면 그 메시지만 가지고는 무엇을 해야할지에 대해 충분히 알려주지 못한다.

 

REST API 디자인 가이드

• URI는 정보의 자원을 표현해야한다.
• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE) 로 표현한다.

 

HTTP Method

GET	GET 메서드는 특정 리소스의 표시를 요청합니다.  GET을 사용하는 요청은 오직 데이터를 받기만 합니다.
POST	POST 메서드는 특정 리소스에 엔티티를 제출할 때 쓰입니다. 이는 종종 서버의 상태의 변화나 부작용을 일으킵니다.
PUT	PUT 메서드는 목적 리소스 모든 현재 표시를 요청 payload로 바꿉니다.
PATCH	PATCH 메서드는 리소스의 부분만을 수정하는 데 쓰입니다.
DELETE	DELETE 메서드는 특정 리소스를 삭제합니다.

put과 patch의 차이는 면접에서도 자주 나오는 질문이다. 

 

URI 설계 시 주의할 점

1. 슬래시(/) 구분자는 계층관계를 나타내는데 사용

http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments  (0)

 

3. 하이픈(-)은 URI 가독성을 높이는데 사용

4. 밑줄(_)은 URI에 사용하지 않는다.

5. URI 경로에는 소문자가 적합하다. 

6. 파일확장자는 URI에 포함시키지 않는다.

http://restapi.example.com/members/soccer/345/photo.jpg (X)

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않습니다. Accept header를 사용하도록 합시다.

    GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

 

Reference:

https://ko.wikipedia.org/wiki/REST#REST_아키텍처에_적용되는_6가지_제한_조건

https://developer.mozilla.org/ko/docs/Web/HTTP/Methods

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