REST

REpresentational State Transfer : 대표적인 상태 전달(직역)

로이 필딩(Roy filding) 2000년 박사 학위 논문에 정의한 웹 기반 소프트웨어 아키텍쳐

정의

• Web에 존재하는 모든 자원(이미지, 텍스트, 동영상, DB등)에 고유한 URL을 부여해 활용
• 자원을 정의하고 자원에 대한 주소를 지정하는 방법론
• HTTP 상 SOAP나 쿠키를 통한 세션 트랙킹 같은 별도의 전송 계층 없이 전송
• 아키텍쳐 형식을 따르면 대규모 소프트웨어 시스템도 설계가 가능

구성요소

1. Resource(자원): HTTP URI
2. Verb(행위): HTTP Method(GET/POST/PUT/DEL/PATCH)
3. Respresentation(표현): JSON, XML, RSS

예시)

# bad
GET /getTodos/1
GET /todos/show/1

# good
GET /todos/1

원리

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

1. 클라이언트/서버 구조

역할이 분명하게 나누고 개발해야 할 내용이 명확학하게 나뉘어지고 서로간 의존성을 낮춤

• 클라이언트 : 사용자 인증, Context(세션, 쿠키 정보 등)을 직접 관리하는 구조
• 서버 : REST API 제공

2. 무상태(Stateless)

Context(세션, 쿠키 정보 등)를 별도 저장하지 않아 서버는 요청만 단순 처리하여 단순화

3. 캐시 처리 기능(Cacheable)

HTTP 표준을 그대로 사용하기 때문에 캐시 처리 가능함(Last-Modifed, E-Tag 등)

4. 계층화(Layered System)

서버 앞 단에 다중 계층('중간' 서버)을 설정하여 사용할 수 있음

• 클라이언트는 대상 서버에 바로 연결되었는지 '중간' 서버를 통해 연결되었는지 알 수 없음
• '중간' 서버는 로드 밸런싱, 암호화 계층, 공유 캐시 기능 등 제공함으로 써 시스템 확장성을 향상시키는데 유용

5. Code on demand(optianal)

코드만 보고도 어떤 행위를 하고 어떤 목적으로 사용되는지 알 수 있음

• Self-descriptiveness : 자체적으로 표현이 가능한 구조
  

6. 인터페이스 일관성(Uniform)

HTTP 표준(URI 표준)만 맞춘다면, 어떤 플랫폼이든 특정 언어나
기술에 종속되지 않고 모든 플랫폼에서 사용 가능

REST API 디자인 가이드

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP Method로 표현한다.

1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)

# bad
GET /members/delete/1

# good
DELETE /members/1   

# bad
GET /members/insert/2
 
# good
POST /members/2 

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

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

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

URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.

REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.

# bad
http://restapi.example.com/houses/apartments/

# good
http://restapi.example.com/houses/apartments 

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

불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있음

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

글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 한다.
이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋다.(가독성)

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

대소문자에 따라 다른 리소스로 인식
RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정

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

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

# bad
http://restapi.example.com/members/soccer/345/photo.jpg

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

8. 리소스 간의 관계를 표현하는 방법

• 리소스 간 연관관계가 있을 경우

 /리소스명/리소스 ID/관계가 있는 다른 리소스명

 GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

• 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다.

GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

9. 자원을 표현하는 Colllection과 Document

• Document : 객체
• Collection : Document의 집합

http://restapi.example.com/sports/soccer

# collection : sports
# document : soccer

http://restapi.example.com/sports/soccer/players/13

# collection : sports, players
# document : 13

위에서 Collection은 복수로 사용하고 있음.
좀 더 직관적인 REST API를 위해서는 Collection과 Document를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있다.

Reference

https://meetup.toast.com/posts/92
https://ko.wikipedia.org/wiki/REST
https://brainbackdoor.tistory.com/53
https://medium.com/@hckcksrl/rest%EB%9E%80-c602c3324196