2024-05-10 [Kotlin+Spring 코틀린 스프링 REST API]

REST API 학습에 들어가기 전

이전 글에서 Event Storming 부분을 간략하게 다루어 보았는데 그중 Command를 다시 한번 기억하고, REST API를 설명해보려 합니다.

2024.05.09 - [분류 전체보기] - 2024-05-09 [Kotlin+Spring DDD 전략적 설계(Strategic Design)]

2024-05-09 [Kotlin+Spring DDD 전략적 설계(Strategic Design)]

Command는 Domain Event를 유발시키는 명령으로, 주로 API와 대응됩니다.

Command를 API로 설계하며 API를 설계하는 방법에는 여러가지가 있습니다. 그중 HTTP 위에서 API를 통한 통신을 하는 REST API에 대해 학습해보려 합니다.

HTTP를 최대한 활용할 수 있다면 좋고, 두 번째로 API 만 보고도 이 API가 어떤 Command를 수행하는 API인지를 알 수 있는 REST(REpresentational State Transfer) 스타일의 API, REST API를 학습해보도록 하겠습니다.

 

REST API 란?

• API(Application Programming Interface)는 애플리케이션이나 디바이스가 서로 간에 연결하여 통신할 수 있는 방법을 정의하는 규칙 세트입니다. REST API는 REST(REpresentational State Transfer) 아키텍처 스타일의 디자인 원칙을 준수하는 API입니다. 이러한 이유로 REST API를 RESTful API라고도 합니다. 즉, 이름 처럼 상태의 전이(State Transfer)를 표현하기 위한 HTTP 상의 아키텍쳐 스타일 입니다.
• 여기서 State는 Resource의 State를 표현하며 이 Resource는 파일, 문서, 데이터 등을 모두 포함합니다.
• REST API Resprensentation(표현)이 핵심인데요, HTTP를 사용하기 때문에 해당 프로토콜을 활용하여 표현합니다. 표현을 위한 구성 요소에 대해 추가적으로 설명드리도록 하겠습니다.

REST 디자인 원칙

가장 기본적인 수준에서 API는 하나의 애플리케이션이나 서비스가 다른 애플리케이션이나 서비스 내의 리소스에 액세스할 수 있게 해주는 메커니즘입니다. 액세스를 수행하는 애플리케이션이나 서비스를 클라이언트라고 하고, 리소스가 포함된 애플리케이션이나 서비스를 서버라고 합니다.

다음의 6가지는 REST 디자인 원칙(아키텍처 제한사항이라고도 칭합니다.)입니다.

 

1. [균일한 인터페이스]

요청이 어디에서 오는지와 무관하게, 동일한 리소스에 대한 모든 API 요청은 동일하게 보여야 합니다. REST API는 사용자의 이름이나 이메일 주소 등의 동일한 데이터 조각이 오직 하나의 URI(Uniform Resource Identifier)에 속함을 보장해야 합니다. 리소스가 너무 클 필요는 없지만, 이는 클라이언트가 필요로 하는 모든 정보를 포함해야 합니다.

2. [클라이언트-서버 디커플링]

REST API 디자인에서 클라이언트와 서버 애플리케이션은 서로 간에 완전히 독립적이어야 합니다.

클라이언트가 알아야 하는 유일한 정보는 요청된 리소스의 URI이며, 이는 다른 방법으로 서버 상호작용할 수 없습니다. 이와 유사하게, 서버  HTTP를 통해 요청된 데이터에 전달하는 것 말고는 클라이언트를 수정하거나 관여하지 않아야 합니다.

 

3. [Stateless]

REST API는 stateless입니다. 이는 각 요청에서 이의 처리에 필요한 모든 정보를 포함해야 함을 의미합니다.

즉, REST API는 서버측 세션을 필요로 하지 않습니다. 서버 애플리케이션은 클라이언트 요청과 관련된 데이터를 저장할 수 없습니다.

4. [캐싱 가능성]

가능하면 리소스를 클라이언트 또는 서버 측에서 캐싱할 수 있어야 합니다. 또한 서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보도 포함되어야 합니다. 이의 목적은 서버 측의 확장성 증가와 함께 클라이언트 측의 성능 향상을 동시에 얻는 것입니다.

 

5. [계층 구조 아키텍처]

REST API에서는 호출과 응답이 서로 다른 계층을 통과합니다. 경험에 따르면 클라이언트와 서버 간 직접 연결된다고 가정하지 않는 것이 좋습니다.

 

6. [코드 온디맨드(옵션)]

REST API는 일반적으로 정적 리소스를 전송하지만, 특정한 경우에는 응답에 실행 코드(예: Java 애플릿)를 포함할 수도 있습니다. 이 경우에 코드는 요청 시에만 실행되어야 합니다.

 

REST 표현을 위한 구성 요소

• URI(Resource) - 먼저 URI 를 통해 Reousrce 이름을 표현합니다. "/models" 다음과 같은 방식으로 표현합니다. 
• Method(Verb) - HTTP의 Method를 사용해 상태를 변경하는 행위(Verb)를 표현합니다. HTTP Method는 GET, POST, PUT, PATCH, DELETE, OPTIONS 로 구성됩니다.
  • GET : Read 요청입니다. Resource의 정보를 획득하기 위해 사용합니다.
  • POST : Create 요청입니다. 새로운 Resource를 생성하기 위해 사용합니다.
  • PUT : Update 요청입니다. Resource에 대한 정보를 수정하기 위해 사용합니다. 수정되는 정보를 포함한 모든 Resource의 정보를 포함하여 요청합니다.
  • PATCH : Update 요청입니다. Resource에 대한 정보를 수정하기 위해 사용합니다. 수정되는 정보만을 요청합니다. (PUT 과거의 유사하나 상황에 따라 PATCH를 사용해야 하는 경우가 있습니다. 대표적으로 강의 수강신청 변경을 신청했고, 승인이나 거절 시 해당 정보만 요청하면 되니 PATCH를 활용할 수 있습니다.)
  • DELETE : Delete 요청입니다. Resource를 삭제하기 위해 사용합니다.
  • OPTIONS : 서버와 클라이언트 사이의 통신 옵션을 확인하기 위해 사용합니다. REST에서 표현을 위해 사용하진 않고, HTTP에서 보안 및 효율성을 위해 자동적으로 생성되는 요청입니다.

 

REST Style API 디자인 가이드

• URI, 즉 Resource의 이름은 명사, 소문자, 복수형을 사용하길 권장합니다.  "/getPosts" 이런식으로 동사를 사용하는 것을 지양해야합니다.
• / 를 통해 Resource 관의 계층 관계를 표현합니다. (/ 는 has 를 의미한다고 보시면 되며, 예를 들어 특정 포스트에 달린 댓글들을 URI로 표현한다면, /posts/{id}/comments 이렇게 표현할 수 있습니다.)
• URI 마지막에 / 를 포함하지 않습니다.
• 언더바 (_)는 사용하지 않아야 하고, 가독성을 높이려면 하이픈(-)을 사용합니다.
• 특정 Resource 하나를 가져올 때 URI에 해당 Resource의 Identifier를 포함하여 표현합니다. ("/posts/{id}" 이런식으로 표현할 수 있습니다.)
• Resource 목록의 페이징(Paging), 필터링(Filtering), 정렬(Sorting), 검색(Searching)을 통해 정보를 가져올시, Path Variable을 활용합니다. ("/posts?page=12" , "/posts?order=latest" 다음과 같은 방식으로 표현할 수 있습니다.)

 

 

REST API를 학습해 본 결과, 디자인 원칙에 대해 추가적으로 학습이나 이해가 필요할 것 같습니다..

강의를 들으며 실습을 하다보니 전체적으로 동작하는 방식이 혼란이 오기 시작했는데, 이럴 때 일수록 개념들을 확실히 정리하고 들어갑시당 ..

화이팅