Rest API에 대해(1)

이번부터 몇번에 거처 Rest API에 대하여 깊게 다루어 볼 예정이다. 이 내용은 gRPG를 이해하기 위한 HTTP/1.1 기반 Rest API에 대하여 정리하기 위함이다. 참고서적은 The Design of Web APIs 책이다.

Rest의 정의

Rest는 Representational State Transfer의 약자로 자원을 이름으로 구분하여 자원의 상태정보를 주고 받는 것을 의미한다. 구체적으로 살펴보면 HTTP URL를 통해 자원을 명시하고 HTTP Method를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.

장점

• HTTP 프로토콜을 사용하여 별도의 인프라 없이 구현 가능
• HTTP 프로토콜을 사용하는 플랫폼에서 사용가능하다
• Rest API에서 메시지 의도하는 바를 명확히 나타내므로 받는 쪽에서 쉽게 파악을 할 수 있다.
• 서버와 클라언트 역할이 명확히 구분된다.

단점

• 표준이 존재하지 않는다.(데이터 표현에 대한)
• 사용하는 method에 4가지 밖에 없다.

특징

• stateless(무상태): HTTP프로토콜은 무상태 프로토콜이므로 REST 역시 무상태이다.
• Cacheable(캐시처리 가능): HTTP가 자긴 캐시 기능을 그대로 사용 할 수 있음
• Layerd System(계층화): 여러 계층을 설계하여 기능 분리와 보안 측면에서 강화 할 수 있다.

Rest API method

Post

Resource를 추가할때 사용된다. Request body에 해당 resource를 담아 요청하는 방식이다. 실제 사용하는 용도와 5가지 method가 매핑하지 않는 경우 Post를 사용하는 것을 추천 한다.

Get

해당 path의 resource를 요청할 때 사용한다. 예를 들어 상품의 정보를 얻을 떄 Get /products/{productId} 을 사용하면 된다. 여기서 ProductId 는 path parameter라고 칭한다. 결과 값은 정의에 따라 json, xml 포맷이 될수 도 있다. 대부분의 경우 json를 기본 포맷으로 사용한다.

Put

이미 존재하는 resource의 정보를 변경하거나 없는 resource를 추가할때 사용된다. 없는 정보를 추가 할때 될 수록 Post를 사용하여 용도를 구분하여 사용하는 것이 좋다.

Patch

이 method는 정보를 업데이트 할떄 사용된다. post 혹은 put으로 업데이트를 구현 할 수 있지만 patch는 해당 resource의 일부 속성을 변경 할 때 자주 사용된다.

Delete

어떤 resource를 삭제할때 사용된다. 이 메서드는 실제 resource.를 삭제 할 수도 있고 해당 resource를 가용하지 않음으로 바꿀 수 도 있다. 예를 들어 기존에 존재하는 상품을 더 이상 사용되지 않지만 기록으로 남겨두고 싶은 경우 해당 상품의 속성을 비가용으로 바꾸면 된다.

API data 설계

API에 사용되는 데이터도 DB혹은 class 설계와 같이 설계를 거쳐야 한다.

기본 데이터 설계 단계

• resource에 사용될 데이터들을 나열
• 나열된 데이터가 사용자 관점에서 필요한지 검토
• 각 method들에 같은 데이터 구조를 사용할지 결정.
• 최종 결정된 데이터들의 타입 결정

아래 작은 예를 들어 위의 3가지를 어떻게 고려 하는지에 대해 알아 보자

//product
name
price
dateAdded
unavailable
warehouses
description
supplier

위에 나열된 데이터는 상품에 필요한 데이터라고 생각해 보자

만약 위의 내용을 일반 소비자가 상품의 상세 내용을 요청했을 경우 그에 대응하는 response를 만들어야 한다면?

unavailable라는 속성과 warehouses라는 속성은 필요없는 속성이므로 제거 해도 될것 같고 재고 있는지에 대하여서만 알려주면 되므로 아래와 같이 설계 할 수 있다.

//product
name
price
dateAdded
definitelyOutOfStock
description
supplier

보여줄 데이터가 결정이 되였으면 이것들의 타입과 꼭 필요여부에 대해 판단하여 최종 설계안을 도출한다.

Name	Type	Required
name	string	yes
price	Int	yes
dateAdded	datetime	yes
definitelyOutOfStock	boolean	no
description	string	no
supplier	object	yes

Response를 도출 단계

여러 method에서 위에서 설계한 product 정보를 response 로 내보내길 원할 수 있다. 요청한 상황에 따라 response되는 data도 상이 해야 한다. 예를 들어 상품 검색에서 나열되는 상품에는 name과 price만 주면 되고 상품의 추가로 인한 response에는 위의 내용들을 모두 넣어 추가한 상품에 대한 교차검증을 할 수 있게 한다. 이렇게 상황마다 처음에 도출한 기본 데이터로부터 삭제 혹은 이름을 변경하여 사용해야 한다.