REST API란?
REST는 “Representational State Transfer”의 약자로 API 작동 방식에 조건을 부여한 소프트웨어 아키텍처이다. HTTP의 주요 저자 중 한 사람인 로이 필딩 (Roy Fielding)의 박사학위 논문에서 웹의 장점을 최대한 활용할 수 있는 모델로써 처음 소개되었다.
REST API는 REST 아키텍처 스타일을 따르는 API를 말한다. 이는 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이라고도 설명할 수 있다.
REST 성숙도 모델(RMM)에 따른 REST API 디자인
레오나르드 리차드슨(Leonard Richardson)은 로이 필딩이 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위한 4단계(0~3단계) 모델을 만들었다. 현실적으로는 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있다.
0단계 : HTTP 프로토콜 사용
단순히 HTTP 프로토콜을 사용하는 단계이다.
이때 모든 요청은 하나의 엔드포인트(Endpoint)로 향한다.
1단계 : 개별 리소스와의 통신 준수
0단계와 달리 개별 리소스에 맞는 엔드포인트를 사용하는 단계이다. 요청할 때처럼, 그에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스의 정보와 리소스 사용이 성공/실패했는지 여부를 반환해야 한다.
한 레스토랑을 예로 들어보자. 손님 A는 음식을 주문하고 손님 B는 예약하고 싶어한다.
0단계에서는 두 손님의 요청에 대한 엔드포인트로 모두 /order 를 사용할 것이다. 하지만 1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용한다.
손님 A: /order
손님 B: /appointment
- 엔드포인트는 명사 형태의 단어로 작성하는 것이 바람직하다. (동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양)
2단계 : CRUD에 맞는 HTTP 메서드 사용
1단계에서 모든 요청에 GET이나 POST 메서드를 사용했다면, 2단계에서는 CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드를 사용한다. 또한 응답 시 의미있는 HTTP Status Code가 반환된다.
- CRUD 메서드
GET: 서버의 데이터(리소스)를 변화시키지 않는 요청에 사용한다.body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달한다.POST: 새로운 리소스를 생성할 때 사용한다.PUT: 서버의 데이터를 새로운 데이터로 교체할 때 사용한다.PATCH: 서버의 데이터를 수정할 때 사용한다.
❓ 멱등성(idempotent)
매 요청에 같은 리소스를 반환하는 특징을 가지는 것을 멱등하다고 한다.
어떤 HTTP 메서드가 멱등성을 가지려면 같은 요청을 한 번 호출하든 여러 번 호출하든 결과가 같아야 한다.
GET: 멱등성 O. 여러 번 조회해도 그 결과는 변화지 않기 때문이다.POST: 멱등성 X. 호출할 때마다 새로운 리소스를 생성하기 때문이다.PUT: 멱등성 O. 여러 번 호출해도 특정 데이터만 새로운 데이터로 수정하기 때문에, 결국 결과는 항상 같기 때문이다.PATCH: 설계에 따라 멱등하기도 하고, 아니기도 하다. 단순히 키값을 바꾸기만 하는 경우에는 멱등하지만, 호출할 때마다 기존 값에 얼마 만큼 더하거나 빼는 형태라면 멱등하지 않기 때문이다.
3단계 : HATEOAS 원칙 준수
HATEOAS는 Hypermedia As The Engine Of Application State의 약자로, 하이퍼미디어(링크)를 통해 애플리케이션의 상태 전이가 가능하도록 하는 원칙을 말한다. 간단하게 설명하자면, 응답에 리소스의 URI를 포함한 링크 요소를 삽입하는 것이다.
예를 들어, 레스토랑의 손님 A가 주문을 완료한 후에 (식사를 마치고) 서비스나 음식에 별점을 남길 수 있도록 해당하는 링크를 작성해 넣을 수 있다. 이렇게 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심이다.
