REST, RESTful하다가 뭐야?
보통 프론트엔드나 백엔드나 학습과정에서 RESTful 한, REST API 설계 라는 말을 많이 들어봤을 것이다. 이 개념에 대해 너무 혼동이 찾아와 가끔은 이상한 소리를 할 때가 있는데 더이상 해메지말고 본격적으로 알아보자.
REST(Representational State Transfer)
REST는 단어 REST가 아닌 Representational State Transfer의 줄임말이다. 이 개념은 2000년 Roy Fielding이 박사 학위 논문에 정의한 개념이며, 프로토콜이나 통신 규약을 말하는 것이 아닌 아키텍쳐 스타일을 말한다.
REST의 궁극적인 목표는 성능, 확장성, 단순성, 수정 가능성, 가시성, 이식성 및 안정성을 높이는 것이다.
REST API 설계 원칙
dr.Roy Fielding은 REST API를 충족시키기 위한 여러 제약조건을 제시했다. 이런 제약 조건들을 준수하여 코드를 작성하면 RESTful하다고 간주할 수 있다.
균일한 인터페이스(Uniform Interface)
동일한 리소스에 대한 모든 API 요청은 출처에 관계없이 동일하게 표시되어야 한다.
사용자이름, 이메일 같은 동일한 데이터는 하나의 URI에 속해야한다.
클라이언트가 필요로 하는 모든 정보를 포함해야 하지만 리소스는 너무 크지 말아야한다.
클라이언트와 서버 분리
REST API에서 서버와 클라이언트는 완전히 독립된 상태여야한다. 클라이언트(응용 프로그램)이 알아야 하는 유일한 정보는 요청된 리소스의 URI여야한다.
다른 방식으로는 서버와 상호작용 할 수 없어야하며, 서버는 HTTP를 통해 요청된 데이터에 전달하는 것 외에는 클라이언트를 수정해서는 안된다.
무상태성(Stateless)
서버와 클라이언트 요청 간 클라이언트에 정보가 저장되지 않으며, 그 반대로도 마찬가지이다. 각 요청이 분리되어 서로 연결되어있지 않는다.
주문 형 코드 (Code on demand)
REST API는 일반적으로 정적인 리소스만 보내지만, 특정 경우 응답으로 실행코드가 포함될 수 있다. 이런 경우 코드는 요청시에만 실행되어야 한다.
캐시 가능성
가능한 경우 리소스는 클라이언트 또는 서버 측에서 캐시가 가능해야한다. 서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보도 포함해야한다.
계층화 된 시스템 아키텍쳐
REST API에서의 요청과 응답은 서로 다른 계층을 거친다. 통신 루프에서 다양한 중개자가 있을 수 있으므로 클라이언트나 서버가 중개자와 통신하는지 여부를 알 수 없더록 설계되어야한다.
위의 원칙을 기반으로 RESTful 한 API 디자인 가이드를 보자
REST API 디자인가이드
첫번째, URI는 정보의 자원을 명사로 표현해야한다.
두번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
A. URI 설계시 주의사항
- 슬래시(/)는 계층 관계를 나타낼 때 사용한다.
https://restapi.example.com/lego/starwars
https://restapi.example.com/pinter/raser- URI 마지막에는 슬래시(/)를 포함하지 않는다.
https://restapi.example.com/lego/starwars해/ 이거안됨
https://restapi.example.com/pinter/raser 이거됨- 가독성을 위해서 ()대신 하이픈(-) 을 사용한다.
밑줄()은 보기 어렵거나 문자가 가려지기도 한다. URI를 쉽게 읽고 해석하기 좋게 하거나, 불가피하게 길다면 가독성을 위해 하이픈(-)을 사용하도록하자. - 파일 확장자는 URI에 포함시키지 말아야한다. 확장자를 사용하기 위해선 Accept header를 사용하자.
GET / group/team-a/screen-shot/a385/images HTTP/1.1 Host: my.example.com Accept: image/png- URI는 반드시 정보의 자원을 표현해야 한다.(리소스 명은 명사로 한다.)
GET /member/delete/1 (x) //행위같은 동사는 표기 금지
Delete /member/1 (o) //자원에 대한 행위는 HTTP 메소드로 표현CRUD Opration
Create(생성): POST : POST를 통해 URI를 요청하면 리소스를 생성한다.
Read(조회): GET : GET을 통해 해당 리소스를 조회한다.
Update(수정): PUT : PUT을 통해 해당 리소스를 수정한다.
Delete(삭제): DELETE : DELETE를 통해 리소스를 삭제한다.
B. 자원을 표현하는 Collection과 Document
Collection과 Document는 모두 리소스라고 표현할 수 있으며 URI에도 표현이 가능하다.
C. 리소스 간의 관계 표현
REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 아래와 같이 표현한다.
GET /리소스명(users)/리소스ID(userId)/관계있는 다른리소스명(devices)관계명이 복잡할 경우 서브 리소스에 명시적으로 표현하는 방법이 있다.
GET /리소스명(users)/리소스ID(userId)/서브 리소스(likes)/관계있는 다른리소스명(devices)응답상태코드
100 ~ : 전송 프로토콜 수준의 정보 교환
200 ~ : 클라이언트 요청이 성공적으로 수행됨
300 ~ : 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
400 ~ : 클라이언트의 잘못된 요청
500 ~ : 서버쪽 오류
최종 결론 REST API
위에서 언급한 Roy Thomas Fielding는 HTTP의 주요 저자중 한 사람이며, HTTP로 통신하는 웹의 장점을 살리고자 6가지 원칙을 정의하였다.
결국 REST API나 RESTful 한 API를 제작한다는 것은, 6가지 원칙을 모두 준수한 API만이 REST API라고 불린다.
ref: "위키 REST","깃헙 REST","IBM REST API","NHNCloude 개발"
