REST, RESTful API

REST란?

 

REST란 Representational State Transfer의 약어로, 로이 필딩의 2000년 박사학위 논문에서 소개되었으며,

월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식입니다.

엄격히 말해 REST는 네트워크 아키텍처 원리의 모음이고, 여기서 '네트워크 아키텍처 원리'란 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반을 일컫습니다. 쉽게 말하면 '네트워크에서 통신을 구성할 때 이런 구조로 설계하라는 지침' 혹은 '설계 가이드'로 말할 수 있습니다.

이러한 가이드에 준수하여 설계한 API를 REST API 혹은 RESTful API라고 합니다.

 

REST API의 구성

 

REST API는 자원(Resource), 행위(verb), 표현(Representations)의 3가지 요소로 구성됩니다.

구성요소	내용	표현 방법
자원 (Resource)	자원	URI
행위 (Verb)	자원에 대한 행위	HTTP 메서드
표현 (Representations)	자원에 대한 행위의 구체적 내용	페이로드

 

이러한 구성 요소를 사용하여 REST API를 설계합니다.

 

REST API 설계 원칙

 

1. URI는 리소스만을 표현하는 데 집중한다.

#bad
GET /getBoardList/1
GET /board/show/1

#good
GET /board/1

 

위 나쁜 예 두 가지를 보게 되면 URI에 행위를 나타내는 getBorardList, show와 같은 동사가 등장한다.

행위는 HTTP 메서드인 GET을 통해서 표현하고, board는 자원에 대한 URI이기 때문에 동사가 아닌 명사를 사용하여 서술한다.

 

2. 행위에 대한 정의는 HTTP 메서드를 통해 설명한다.

#bad
GET /board/delete/1

#good
DELETE /board/1

 

위와 마찬가지로 DELETE라는 행위는 HTTP 메서드 명시로 서술하며, URI로 서술하지 않는다.

 

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

GET /korea/companies/kakao/employee/1

 

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

GET /korea/companies/kakao/employee/1/

 

URI는 유일한 자원에 대한 명시이기 때문에 혼동을 주지 않도록 마지막에 계층을 나타내는 슬래시는 포함하지 아니한다. 

 

5. 불가피하게 긴 URI 경로를 사용하게 되면, 하이픈 ( - )을 사용하며 언더바(  _  )는 사용하지 않는다.

#bad
GET /korea/companies_list/kakao/employee/1

#good
GET /korea/companies-list/kakao/employee/1

 

구분자를 포함해야한다면 가독성을 위해 언더바가 아닌 하이픈을 사용한다.

 

6. URI 경로에는 대문자 사용을 지양한다.

#bad
GET /Korea/companiesList/Kakao/Employee/1

#good
GET /korea/companies-list/kakao/employee/1

 

RFC 3986은 URI를 scheme 혹은 host componenent를 제외하고 대소문자를 구분하도록 정의하기 때문에, 혼동을 방지하기 위해 소문자 사용을 지향한다.

 

7. 파일 확장자는 URI에 포함하지 않는다.

#bad
GET /korea/companies-list/kakao/employee/{ 1 }/profile-img.jpg

#good
GET /korea/companies-list/kakao/employee/{ 1 }/profile-img

 

HTTP 요청 메서드를 사용하여 해당 자원의 포맷을 나타내기 위해선 URI가 아닌 HTTP 메세지의 accept 속성을 사용한다.