[네트워크]REST API

지난번 글에서, 서버의 구성을 모르는 클라이언트를 위해

 

서버가 준비한 메뉴판이 API(Application Programming Interface)라고 했었다.

 

관련 글: https://gnidinger.tistory.com/441

[네트워크]HTTP

 

만약 식당에 갔는데 메뉴판이 아래와 같이 생겼다면 어떨까?

 

출처: https://blog.kulturekonnect.com/9-menu-design-fails

7 Restaurant Menu Design FAILS

알아보기도 어려울뿐더러 주문할 때까지 시간이 한참 걸릴 것이다.

 

누가 봐도 저 메뉴판이 좋은 디자인을 가지지 못한 이유다.

 

API의 설계도 이와 같은데, HTTP를 기반으로 요청과 응답을 통해 리소스를 주고받기 위해선 잘 디자인된 API가 필요하다.

 

지난번에 언급 했듯이 HTTP API 디자인에는 Best Practice가 있으며,

 

이를 REST(Representational State Transfer) API라 부른다.

 

미국의 컴퓨터과학자 로이 필딩(Roy Fielding)의 박사논문을 바탕으로 레너드 리처드슨(Leonard Richardson)이 만든

 

4단계 성숙도 모델이 RESI API의 기준이 되는데, 이는 아래와 같다.

 

REST 성숙도 모델은 총 4단계(0~3단계)로 이루어지며,

 

로이 필딩은 모델의 모든 단계를 충족해야 REST API라 부를 수 있다 주장했다.

 

실제로는 2단계까지만 충족해도 좋은 API 디자인이며, 이를 HTTP API라 따로 부르기도 한다.

 

그럼 각 단계에 대해 살펴보자.

 

• REST 성숙도 모델 - 0단계

0단계에서는 단순히 HTTP를 사용하기만 하면 된다.

 

허준이라는 주치의의 예약 가능한 시간을 확인하고, 약속을 잡는 상황을 예로 들어보자.

 

위에 설명한 것처럼 단순한 HTTP를 사용하고 있는 것을 확인할 수 있다.

 

• REST 성숙도 모델 - 1단계

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

 

클라이언트는 수행할 액션과 매개변수가 지정된 POST 요청을 하는데,

 

구체적으로는 HTTP POST 요청을 하여 액션과 대상, 필요한 매개변수를 Endpoint에 전달한다.

 

여기서 Endpoint란 리소스에 접근할 수 있도록 해주는 URI라고 보면 된다.

 

0단계 모델에서는 /appointment를 유일한 엔드포인트로 썼지만, 

 

1단계에서는 요청할 리소스에 따라 다른 엔드포인트를 사용한다.

 

위 예시를 보면 시간 확인과 예약 단계에서 각각 다른 엔드포인트를 사용한 것을 확인할 수 있다.

 

여기서 적절한 엔드포인트의 작성이 중요해지는데,

 

엔드포인트 작성 시에는 동사, HTTP 메서드 등은 피하고 리소스에 집중해 명사 형태의 단어로 작성하는 것이 좋은 방법이다.

 

또한 요청에 대한 응답으로 리소스 사용에 대한 성공/실패 여부를 반환해야 하는데, 그 예는 아래와 같다.

 

9시(id: 123)에 예약을 진행하였으나 실패한 것을 확인할 수 있다.

 

• REST 성숙도 모델 - 2단계

2단계부터는 CRUD에 맞는 적절한 HTTP 메서드를 사용하는 것이 중요해진다.

 

1단계까지의 예시에선 CRUD에 상관없이 모든 요청을 POST로 하고 있다.

 

상황에 맞는 적절한 메서드를 사용하는 예에 대해 보자.

 

예약 시간을 조회하기 위해 GET 메서드를, 예약을 생성하기 위해 POST 메서드를 사용했다.

 

GET 메서드엔 Body가 없기 때문에 Query Parameter를 사용하여 필요한 리소스를 전달한다.

 

응답의 경우도 201 Created로 명확하게 작성해야 하며,

 

관련된 리소스를 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 해야 한다.

 

메서드를 사용할 때의 대략적인 규칙은 아래와 같다. 

 

메서드	기능	규칙
OPTIONS	해당 URL에서 지원하는 요청 메세지의 목록을 요청
GET	URL에 해당하는 자료의 전송을 요청	서버의 데이터를 변화시키지 않는 요청
POST	서버에서 처리할 수 있는 자료를 보낸다. 멱등성*을 보장하지 않는다.	요청마다 새로운 리소스 반환
PUT	지정한 URL에 지정한 데이터를 저장할 것을 요청	요청마다 같은 리소스 반환 / 내용 교체
PATCH	지정한 URL의 데이터를 부분적으로 수정할 것을 요청	내용 수정
DELETE	지정한 URL의 정보를 제거할 것을 요청

*멱등성 - 연산을 여러 번 적용하더라도 결과가 달라지지 않는 성질

 

앞서 언급했듯이, API를 디자인할 때 2단계까지만 적용되어도 잘 만든 API라 할 수 있다.

 

• REST 성숙도 모델 - 3단계

3단계는 HATEOAS(Hypertext As The Engine Of Application State - 애플리케이션 상태 엔진으로써의 하이퍼미디어)

 

원칙에 기반하여 설계하는 것이다.

 

쉽게 말하면 요청에 반환되는 응답에 리소스에 대한 링크를 삽입하는 것인데, 예를 들면 아래와 같다.

 

예약 시간을 확인한 후에는 그 시간대에 예약할 수 있는 링크를 삽입하거나,

 

예약을 확정하고 나서는 그 예약을 다시 확인할 수 있는 링크가 삽입되었다.

 

이렇게 좋은 API를 만드는 법에 대해서 알아보았는데, 아래와 같이 짧게 요약할 수 있겠다.

 

• 규칙을 통한 리소스 중심의 올바른 엔드포인트 작성
• 적절한 응답 코드와 리소스에 대한 정보 기재
• CRUD에 적합한 HTTP 메서드 사용
• 응답에 리소스에 대한 링크 삽입