[네트워크] REST API

REST API

• Representational State Transfer API의 약자입니다.
• 2000년도에 로이 필딩의 박사학위 논문에 최초로 공개되었습니다.
• 로이 필딩은 HTTP를 만든 사람 중 한명인데, HTTP의 우수성에 비해 제대로 사용되지 못하는 모습이 안타까워 웹의 장점을 최대한 활용할 수 있는 아키텍쳐로써 REST를 발표했다고 합니다.

REST의 구성

• 자원 (Resource) - URI
• 행위 (Verb) - HTTP Method
• 표현 (Representations)

 

REST의 특징

Uniform - 유니폼 인터페이스

• 유니폼 인터페이스는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍쳐 스타일을 말합니다.

Stateless - 무상태성

• REST는 무상태성을 갖습니다. 다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다.
• 세션 및 쿠키 정보를 별도로 저장하지도 관리하지도 않기 때문에 API 서버는 들어오는 요청만 단순히 처리하면 됩니다.
• 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.

Cacheable - 캐시 가능

• REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능합니다.
• 따라서 HTTP가 가진 캐싱 기능이 적용 가능합니다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태크나 E-Tag를 이용하면 캐싱 구현이 가능합니다.

Self-Descriptiveness - 자체 표현 구조

• REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있습니다.

Client-Server 구조

• REST 서버는 API 제공, 클라이언트는 사용자 인증이나 세션, 로그인 정보 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야할 내용이 명확해지고 서로간의 의존성이 줄어듭니다.

계층형 구조

• REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 프록시, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게합니다.

 

REST API 디자인 가이드

• URI는 정보의 자원을 표현해야한다.
• 자원에 대한 행위는 GET,POST,PUT,DELETE로 표현한다.
• 다른 건 다 잊어도 이 두 가지는 꼭 기업합시다.

REST API 중심 규칙

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

GET /members/delete/1

위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원을 표현하는데 중점을 두어야합니다.

delete와 같은 행위에 대한 표현이 들어가서는 안됩니다.

• 자원에 대한 행위는 HTTP Method 로 표현합니다.

위의 잘못된 URI를 수정해보면

DELETE /members/1

로 수정합니다.

회원 정보를 가져올 때는 GET, 회원 추가 시의 행위를 표현하고자 할 때는 POST를 사용합니다.

• 회원정보를 가져오는 URI

GET /members/show/1 (x)
GET /members/1 (o)

• 회원을 추가할 때

GET /members/insert/2 (x)
POST /members/2 (o)

URI 설계 시 주의할 점

• / 는 계층 관계를 나타내는 데 사용
• URI 마지막 문자로 슬래시를 포함하지 않음
• - 은 URI 가독성을 높이는데 사용
• _는 사용하지 않는다
• URI경로에는 소문자가 적합
• 파일 확장자는 URI에 포함시키지 않는다

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

• REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현 방법으로 사용합니다.

/리소스명/리소스 ID/관계가 있는 다른 리소스명
GET : /users/{userid}/devices (일반적으로 소유의 관계를 표현할 때)

• 만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 좋아하는 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.

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

자원을 표현하는 Collection과 Document

• Collection가 Document에 대해 알면 URI 설계가 한 층 더 쉬워집니다. Document는 단순히 문서로 이해해도 되고, 한 객체라고 이해하셔도 됩니다. Collection은 문서들의 집합, 객체들의 집합이라고 생각하시면 이해하시는데 좀 더 편합니다.
• Collection과 Document는 모두 리소스라고 표현할 수 있으며 URI에 표현됩니다.

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

• 위 URI를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있다고 생각하면 됩니다.

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

• sports, players 컬렉션과 soccer,13을 의미하는 도큐먼트로 URI가 만들어집니다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다. 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.