REST API

SuJin·2022년 10월 6일

: 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로써 처음 소개됨

웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 포로토콜을 통해 요청과 응답을 정의하는 방식

클라이언트와 서버 사이에는 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위한 메뉴판이 필요.

이 메뉴판을 보고 클라이언트는 식당에서 식사를 주문하듯 서버에 요청, 이에 대한 응답을 메뉴판에 있는 사진이나 음식에 대한 설명처럼 다시 서버에서 클라이언트로 전송

→ HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판 필요 ⇒ API가 수행

모두가 잘 알아볼 수 있도록 작성해야한다.

REST API를 디자인하는 방법

REST API를 잘 적용하기 위한 4단계 모델

이 모델의 모든 단계를 충족해야 REST API라고 부를 수 있다

3단계까지 지키기 어려워서 2단계까지만 적용해도 좋은 API 디자인. → HTTP API

0단계에서는 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

이 경우에서는 해당 API를 REST API 라고 할 수는 없지만,

0단계는 REST API를 작성하기 위한 기본단계

ex) 허준 이라는 이름의 주치의의 예약 가능한 시간을 확인하고, 어떤 특정 시간에 예약하는 상황 예시

HTTP 프로토콜을 사용하는 예시

단순히 HTTP 프로토콜을 사용하는 것이 REST API의 출발점

1단계에서는 개별 리소스(Resource)와의 통신을 준수해야한다

REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현

→ 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것이 1단계의 핵심

1단계에서는 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용

예약 가능한 시간 확인이라는 요청의 응답으로 받게 되는 자원(리소스)은 허준이라는 의사의 예약 가능한 시간대. → 요청시 /doctors/허준 이라는 엔드포인트 사용
특정 시간에 예약 시, 실제 slots 라는 리소스의 123이라는 id를 가진 리소스가 변경되기 때문에, 하단의 특정 시간에 예약이라는 요청에서는 /slots/123 으로 실제 변경되는 리소스를 엔드포인트로 사용
어떤 리소스, 응답을 사용하는지에 따라 각기 다른 엔드포인트를 사용하기에, 적절한 엔드포인트를 작성하는것이 중요함
엔드포인트 작성시
- 동사, HTTP 메서드, 어떤 행위에 대한 단어 사용 지양
- 리소스에 집중해 명사 형태의 단어로 작성
요청에 따른 응답으로 리소스 전달시, 사용한 리소스에 대한 정보와 리소스 사용에 대한 성공/실패 여부 반환 ex) 김코딩 환자가 9시에 예약을 진행하였으나 해당 시간이 마감되어 예약이 불가능할시, 아래 예시처럼 리소스 사용에 대한 실패 여부를 포함한 응답을 받아야 한다

CRUD에 맞게 적절한 HTTP 메서드를 사용

예약 가능한 시간을 확인한다 = 예약 가능한 시간을 조회(READ)

특정 시간에 예약한다 = 해당 특정 시간에 예약을 생성(CREATE)

HTTP 메서드 사용시 유의해야하는 규칙

GET 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용
POST 메서드는 요청마다 새로운 리소스 생성
PUT 메서드는 요청마다 같은 리소스 반환 → 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다 → 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST 는 구분하여 사용
PUT 메서드와 PATCH 메서드도 구분하여 사용
PUT 은 교체, PATCH는 수정의 용도로 사용