REST API
REST는 Representational State Transfer 의 약자로, 로이 필딩(Roy Fielding)의 논문에서 웹의 장점을 최대한 활용할 수 있는 아키텍처로 처음 소개되었다.
REST API란, 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI 로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말한다.
HTTP 프로토콜을 기반으로 요청, 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽게 잘 작성된 API가 필요하기 때문에 REST API 디자인이 중요하다.
- 자원(Resource) : URI
- 행위(Verb) : Http Method
- 표현(Representations)
REST API 규칙
레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.
로이 필딩은 이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했다. 하지만 실제로 3단계까지 지키기 어렵기 때문에, 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있다.
REST API 0단계(HTTP 사용)
0단계는 REST API를 작성하기 위한 기본 단계로, HTTP 프로토콜을 사용하는 것이 기본이 된다.
REST API 1단계(개별 리소스와의 통신 준수)
1단계는 개별 리소스와의 통신을 준수해야 하는데, 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 핵심이다.
1단계에 비하면 /doctors , /slots 등 각기 다른 엔드포인트로 구분되어 사용된 것을 볼 수 있다.
어떤 리소스를 변화시키는지, 또는 어떤 응답이 제공되는지에 따라 각기 다른 엔드포인트를 사용하기 때문에 적절한 엔드포인트 작성이 중요하다.
엔드포인트 작성시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용을 지양하고 resource 에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.
요청에 따른 응답으로 리소스를 전달할 시, 리소스 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환 해야 한다.
REST API 2단계(HTTP 메서드 원칙 준수)
2단계에서는 CRUD 에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다.
0~1단계까지는 모든 요청을 POST 메서드를 사용했지만 이건 적합한 메서드를 사용한 것으로 볼 수 없다.
예약 가능한 시간을 확인할 때에는 시간을 조회(READ) 하여야 하고, 예약할 때에는 예약을 생성(Create) 하여야 한다.
또한 생성할 시 POST 메서드를 사용하여 요청을 보내면 응답이 어떻게 반환되는지도 중요하다. 새롭게 생성된 리소스를 보내주기 때문에 응답코드가 201 Created 로 명확하게 작성되어야 하며, 클라이언트가 Location header 에 작성된 URI를 통해 확인할 수 있도록 하여야 한다.
HTTP 메서드를 사용할 때의 규칙
GET메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.POST메서드는 요청마다 새로운 리소스를 생성하고PUT메서드는 요청마다 같은 리소스를 반환하는데, 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 멱등성을 가지는 메서드PUT과 그렇지 않은 메서드POST는 구분하여 사용해야 한다.PUT메서드와PATCH메서드도 구분하여 사용해야 한다.PUT은 교체,PATCH는 수정의 용도로 사용한다.
REST API 3단계(HATEOAS 원칙 준수)
HATEOAS란 Hypermedia As The Engine Of Application State 의 약자로 하이퍼미디어 컨트롤을 적용한다. 요청은 2단계와 동일하나 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.
만약 예약 가능 시간 정보를 요청했다면, 응답과 함께 예약 가능한 링크를 삽입하거나 예약 확인의 링크를 포함해 작성하는 경우가 해당한다.
REST 특징
1. Uniform
균일한 인터페이스는 모든 RESTful 웹 서비스의 디자인 기본이다. URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다.
2. Stateless
REST는 무상태성 성격을 가진다. 모든 요청은 따로 쿠키나 세션 등으로 저장되거나 관리되지 않기 때문에 API 서버는 들어오는 요청만을 단순하게 처리한다. 이로 인해 서비스의 자유도가 높아지고 불필요한 정보 관리를 줄여 구현이 단순해진다.
3. Cacheable
HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹 인프라를 그대로 활용이 가능하다. 따라서 HTTP가 가진 캐싱 기능 적용이 가능하다.
RESTful 웹 서비스는, 캐시 가능 또는 불가능으로 정의되는 API 응답을 사용하여 캐싱을 제어한다.
4. Self-descriptiveness
자체 표현 구조라는 뜻으로, REST API 메세지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있다는 특징이 있다.
5. Client - Server
REST 서버는 API 제공을 하고, 클라이언트는 사용자 인증이나 세션 및 로그인 정보를 직접 관리하는 구조로 각각의 역할이 확실하게 분담된다. 따라서 Client와 Server에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.
6. 계층형 구조
REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상 유연성을 둘 수 있다.
클라이언트는 클라이언트와 서버 사이의 다른 중개자에게도 연결할 수 있고, 서버로부터 응답을 받을 수도 있다.
CRUD
GET, POST, PUT, PATCH, DELETE 등 Method로 CRUD가 가능하다.
- GET : 리소스를 조회하고 해당 document에 대한 자세한 정보를 가져온다.
- POST : 해당 URI를 요청하면 리소스를 생성한다.
- PUT : 해당 리소스를 수정한다.
- DELETE : 해당 리소스를 삭제한다.
URI 설계 시 주의할 점
- REST API는 분명한 URI를 만들어 통신하는 것으로, URI의 마지막에
/슬래시를 사용하지 않는다.
http://www.naver.com/ (X)
http://www.naver.com (O)- 불가피하게 긴 URI 경로를 사용하게 될 경우 하이픈을 사용할 수 있다.
http://www.jang-jiwoo-blog-git.com- 밑줄은 사용하지 않는다.
- 소문자가 적합하다.
- 파일 확장자는 URI에 포함시키지 않는다.
HTTP 응답 상태 코드
- 200 : 클라이언트의 요청을 정상적으로 수행
- 201 : 어떠한 리소스 생성 요청시, 성공적으로 생성됨을 알림(POST)
- 400 : 클라이언트의 요청이 부적절할 경우
- 401 : 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때(비회원이 회원만 볼 수 있는 페이지에 접근하는 경우)
- 403 : 유저 인증 상태와 관계 없이, 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용(403 자체는 리소스가 존재한다는 뜻이기 때문에 404나 400을 사용 권고)
- 405 : 클라이언트가 요청한 리소스에 사용 불가능한 Method를 이용했을 경우
- 301 : 요청한 리소스에 URI가 변경 되었을 때 사용(Location header에 변경된 URI 적어줘야 함)
- 500 : 서버 문제가 있을 경우
Reperence
