[1]의 5장은 API 설계에서 엔드포인트와 동작을 정의하는 방법에 대한 내용을 다루고 있다. 엔드포인트의 설계는 API의 아키텍처에서 중요한 부분으로, 요청 및 응답 메시지의 구조뿐만 아니라 엔드포인트 배치와 동작도 고려해야 한다.
엔드포인트의 역할은 크게 데이터 지향(Information Holder)과 활동 지향(Processing Resource)으로 나뉜다.
활동 지향 엔드포인트 역할은는 계산, 상태 변경 등의 동작을 수행하며, 클라이언트가 원격으로 처리 작업을 요청할 수 있도록 한다. 데이터 지향 엔드포인트 역할은는 데이터의 읽기/쓰기 접근을 지원하며, 데이터의 수명 및 변경 가능성에 따라 다양한 유형으로 분류됩니다. 우선, 활동 지향 관련해서 처리 리소스 패턴들과 데이터 지향 관련해서는 정보 보유자 패턴으로 나누어 살펴 보자.
처리 리소스
처리 리소스와 관련된 패턴들은 주로 활동 지향 엔드포인트를 설계하는 데 사용된다. 이 패턴들은 API가 클라이언트로부터 요청을 받아 어떤 작업을 수행하거나 상태를 변경할 수 있게 하는데, 이를 통해 다양한 비즈니스 로직을 처리할 수 있다. 주요 패턴과 그 특징은 다음과 같다.
1. 계산 함수 (Computational Function)
설명: 입력 값을 받아 계산 작업을 수행하고, 그 결과를 반환하는 동작.
주요 특징:
- 상태 비저장(stateless)으로 동작하며, 단순하거나 복잡한 연산 작업을 수행.
- 클라이언트가 제공한 입력에 따라 예측 가능한 결과를 생성.
- 연산의 반복 호출 시 일관된 결과를 보장.
포스 충돌:
- 응답 시간 대 정확성: 빠른 계산을 위해 성능 최적화가 필요하지만, 정확성을 유지해야 함.
- 표현력 대 단순성: 더 많은 계산 기능을 제공할수록 API가 복잡해지고 학습이 어려워질 수 있음.
2. 인출 동작 (Retrieval Operation)
설명: 데이터를 조회하여 클라이언트에게 반환하는 읽기 전용 작업.
주요 특징:
- 안전한 읽기 작업으로 상태를 변경하지 않음.
- 다양한 데이터 소스로부터 데이터를 집계하여 제공할 수 있음.
- 멱등성 보장으로 같은 요청에 대해 항상 같은 결과 반환.
포스 충돌:
- 확장성 대 일관성: 여러 클라이언트의 동시 요청에 대해 일관된 데이터를 빠르게 제공해야 함.
- 캐싱 대 최신성: 캐싱을 사용하면 응답 속도를 높일 수 있지만, 데이터의 최신성을 보장하기 어려울 수 있음.
3. 상태 생성 동작 (State Creation Operation)
설명: 클라이언트 요청을 받아 새로운 리소스나 객체를 생성하는 작업.
주요 특징:
- 쓰기 작업으로, 데이터를 생성하고 이를 시스템에 저장.
- 생성된 리소스에 대한 ID나 참조를 반환하여 후속 작업에 사용 가능.
- 입력 데이터의 유효성 검사가 필요.
포스 충돌:
- 유효성 대 성능: 유효성 검사를 철저히 할수록 성능이 저하될 수 있음.
- 데이터 중복 대 일관성: 동일한 요청을 반복 처리할 때 데이터 중복 생성 문제가 발생할 수 있음.
4. 상태 전이 동작 (State Transition Operation)
설명: 기존 리소스의 상태를 변경하거나 업데이트하는 작업.
주요 특징:
- 읽기-쓰기 작업으로, 리소스의 상태를 업데이트하거나 수정.
- 상태 변경에 대한 명확한 정의가 필요하며, 멱등성을 고려하여 반복 호출 시 결과가 일관되게 유지.
- 예를 들어, 주문 상태를 "처리 중"에서 "배송 중"으로 전환.
포스 충돌:
- 멱등성 대 복잡성: 상태 변경 작업의 멱등성을 보장하려면 복잡한 설계가 필요할 수 있음.
- 성능 대 일관성: 빠른 상태 전환을 위해 비동기 처리를 사용하면 일관성을 유지하기 어려울 수 있음.
정보보유자
정보 보유자와 관련된 패턴들은 주로 데이터 지향 엔드포인트 설계에 사용된다. 이 패턴들은 API가 데이터를 클라이언트에게 제공하고, 필요에 따라 데이터를 읽고 쓰는 작업을 지원하도록 돕는다. 주요 패턴과 그 특징은 다음과 같다.
1. 운용 데이터 보유자 (Operational Data Holder)
설명: 일상적으로 자주 변경되는 데이터를 관리하며, 클라이언트가 데이터 생성, 읽기, 업데이트, 삭제(CRUD) 작업을 수행할 수 있도록 지원.
주요 특징:
- 읽기-쓰기 작업을 지원하며, 실시간 데이터 처리가 중요한 경우 사용.
- 짧은 수명의 데이터를 자주 업데이트하며, 빠른 응답과 처리 속도가 요구됨.
- 예: 쇼핑몰의 주문 내역, 은행 계좌 거래 내역.
포스 충돌:
- 속도 대 데이터 일관성: 빠른 데이터 처리가 중요하지만, 데이터 일관성을 유지해야 함.
- 가용성 대 보안: 데이터를 자주 사용하고 접근할 수 있어야 하지만, 민감한 정보일 경우 보안 조치를 강화해야 함.
2. 마스터 데이터 보유자 (Master Data Holder)
설명: 상대적으로 안정적이고, 자주 변경되지 않는 주요 참조 데이터를 관리하는 리소스.
주요 특징:
- 읽기 전용 또는 제한된 쓰기 작업을 지원하며, 주요 비즈니스 데이터를 안정적으로 제공.
- 변경 빈도가 낮으며, 데이터의 일관성과 품질을 유지하는 데 중점.
- 예: 고객 정보, 제품 카탈로그.
포스 충돌:
- 일관성 대 성능: 데이터 일관성을 유지해야 하지만, 이를 위해 성능이 저하될 수 있음.
- 확장성 대 최신성: 클라이언트의 확장성 요구에 따라 성능을 높이면서도, 데이터가 최신 상태임을 보장해야 함.
3. 참조 데이터 보유자 (Reference Data Holder)
설명: 국가 코드, 통화 코드 등 기본적이고 자주 변경되지 않는 참조 데이터를 제공하는 리소스.
주요 특징:
- 읽기 전용으로 제공되며, 고정된 데이터를 여러 클라이언트가 참고할 수 있음.
- 데이터 변경이 드물기 때문에 캐싱을 통해 빠른 응답이 가능.
- 예: 언어 코드, 국가 및 지역 코드.
포스 충돌:
- 최신성 대 캐싱 효율성: 캐싱을 사용하여 성능을 높이려 하지만, 데이터의 정확성과 최신성을 보장해야 함.
- 보안 대 접근성: 특정 참조 데이터를 보안이 필요한 경우 접근 제한이 필요하지만, 동시에 다양한 클라이언트가 접근할 수 있어야 함.
4. 데이터 전송 리소스 (Data Transfer Resource)
설명: 클라이언트 간 데이터 공유 및 전송을 위한 임시 저장소 역할을 하는 리소스.
주요 특징:
- 클라이언트가 데이터를 임시로 저장하고, 다른 클라이언트로 전송할 수 있음.
- 단기 보유 및 관리로, 데이터를 저장한 후 일정 시간이 지나면 삭제하거나 이동.
- 예: 파일 업로드/다운로드 서비스, 메일 서버의 큐.
포스 충돌:
- 저장 기간 대 가용성: 데이터를 얼마나 오랫동안 보관할 것인지와 이를 쉽게 접근할 수 있도록 할 것인지 간의 균형.
- 보안 대 효율성: 전송 데이터를 암호화하고 보호해야 하지만, 이를 처리하는 과정에서의 성능 저하를 방지해야 함.
5. 링크 조회 리소스 (Link Lookup Resource)
설명: 다른 정보 보유자 리소스로의 링크를 제공하며, 데이터 관계를 유지하고 탐색을 지원하는 리소스.
주요 특징:
- 읽기 전용으로, 다른 리소스 간의 관계를 정의하고 참조를 관리.
- 데이터 관계를 명확히 하여 클라이언트가 다른 리소스 간의 데이터 연결을 쉽게 탐색할 수 있게 함.
- 예: 제품과 관련된 리뷰, 고객과 관련된 주문 내역.
포스 충돌:
- 데이터 연결성 대 독립성: 여러 리소스를 연결해야 하지만, 각 리소스는 독립적으로 관리되어야 함.
- 응답 시간 대 일관성: 빠르게 데이터 관계를 조회해야 하지만, 데이터의 일관성을 유지해야 함.
참고 문헌
[1] 올라프 짐머만 , 미르코 스토커 , 다니엘 뤼브케 , 우베 즈둔 , 세자레 파우타소 , "마이크로서비스 API 디자인 패턴: 쉬운 통합을 위한 결합도 최적화 전략" 에이콘. 이승범 역