[HTTP/Network] REST API

Hannahhh·2022년 8월 5일

HTTP/Network

목록 보기

5/12

🔍 REST API

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

식당에서 식사를 주문하기 위해 메뉴판이 있는 것과 같이, Client와 Server 사이에도 데이터와 리소스를 요청하고, 요청에 따른 응답을 전달하기 위한 메뉴판이 필요하다. 이때, HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판이 필요하며, 이 역할을 API가 수행한다.

👀 REST API Design

아래는 로이 필딩의 REST방법론을 보다 더 실용적으로 적용하기 위한 Richardson의 REST 성숙도 모델이다.

REST 성숙도 모델은 총 4단계로 나누어지며, 모든 단계를 지키기 어렵기 때문에 2단계까지만 적용해도 좋은 API라고 볼 수 있다.(HTTP API)

✔ REST 성숙도 모델 - 0단계

REST API를 작성하기 위한 기본 단계로, 단순히 HTTP 프로토콜을 사용하기만 해도 된다.

아래는 허준이라는 이름의 주치의의 예약 가능한 시간을 확인하고, 특정 시간에 예약하는 상황을 예시이다.

✔ REST 성숙도 모델 - 1단계

개별 리소스와의 통신을 준수해야한다.

REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현하기 때문에 모든 자원은 개별 리소스에 맞는 엔드 포인트(Endpoint)를 사용해야 하며, 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다.

위의 0단계에서는 요청에서의 엔드포인트로 모두 /appointment를 사용했지만, 1단계에서는 아래와 같이 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 사용한다.

위의 예시에서 예약 가능한 시간 확인이라는 요청의 응답으로 받게 되는 자원(리소스)은 허준이라는 의사의 예약 가능한 시간대이므로, 요청 시 /doctors/허준 이라는 엔드포인트를 사용했다.

또한, 특정 시간에 예약하게 되면 실제 slots라는 자원의 123이라는 id를 가진 자원이 변경되기 때문에, 특정 시간에 예약이라는 요청에서는 /slots/123으로 실제 변경되는 리소스를 엔드포인트로 사용했다.

엔드포인트 작성 시 동사, HTTP 메서드, 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어를 사용하는 것이 좋다.

더불어 요청에 따른 응답으로 리소스를 전달할 때에도 사용한 리소스에 대한 정보와 함께 아래와 같이 리소스 사용에 대한 성공/실패 여부를 반환해야 한다.

✔ REST 성숙도 모델 - 2단계

CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드를 사용해야 한다.

CURD 메서드?

앞서 0단계, 1단계 예시에서는 모든 요청을 CRUD와 상관없이 POST 메서드를 사용하고 있기 때문에 CRUD에 따른 적합한 메서드를 사용한 것이 아니다.

먼저 예약 가능한 시간을 확인한다는 것은 예약 가능한 시간을 조회(READ)하는 행위를 의미하기 때문에 GET 메서드를 사용해 요청을 보내는데, GET 메서드는 body를 가지지 않으므로 query parameter를 사용해 리소스를 전달한다.

또한, 특정 시간에 예약한다는 것은 해당 특정 시간에 예약을 생성(CREATE)하는 행위를 의미하기 때문에POST 메서드를 사용하여 요청을 보내야 한다.
이때,POST 요청에 대한 응답은 새롭게 생성된 리소스를 보내주기 때문에 응답 코드는 201 Created 로 명확하게 작성해야 하며, 관련 리소스를 Client가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 볼 수 있다.

⭐ HTTP 메서드를 사용할 때 유의해야할 몇가지 규칙

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