오래된 SW 엔지니어의 평생 공부

[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 디자인 패턴: 쉬운 통합을 위한 결합도 최적화 전략" 에이콘. 이승범 역

[1]은 API 설계에 관한 심도 있는 가이드로, 1장에서는 API 설계에 필요한 기본 개념과 패턴을 다룹니다. 주요 내용은 다음과 같다.

API 기본 개념:
API(Application Programming Interface)가 무엇인지 설명하고, 현대 소프트웨어 아키텍처에서 API의 중요성을 강조한다. API 설계에서 자주 겪는 문제(결합도, 세분화 등)를 설명하고, API가 어떻게 기능을 노출하면서도 구현 세부 사항을 숨기는지 설명한다.

원격 API:
API가 서로 다른 서버나 지역에 분산된 애플리케이션 간의 통신을 어떻게 가능하게 하는지 다룬다. RPC, SOAP, REST와 같은 다양한 원격 API 기술이 등장한 역사와 발전 과정을 설명한다.

API 설계의 어려움과 패턴:
다양한 클라이언트의 요구를 충족시키면서 확장성과 유지보수가 가능한 API 설계의 어려움에 대해서 설명한다. API를 모듈화하고 유연성을 유지하면서도 호환성을 지키는 설계 전략을 제시한다.

아키텍처적으로 중요한 요구 사항:

1장에서는 다음과 같은 내용을 언급한다.

• 이해 가능성: API의 요청 및 응답 메시지 구조는 이해하기 쉽고, 불필요한 복잡성을 피해야 한다. 이를 위해 API는 도메인 모델을 따르는 것이 좋다. 중요한 점은 내부 구현 세부 정보가 외부에 드러나지 않도록 해야 한다.
• 정보 공유와 정보 숨기기: API 설계에서 중요한 것은 클라이언트가 필요로 하는 정보를 정의하면서도, 불필요한 세부 사항을 숨기는 것이다. 구현 세부 정보가 외부로 노출되면 API가 진화할 때 클라이언트에 부정적인 영향을 미칠 수 있다.
• 결합도(Coupling): 느슨한 결합(Loose Coupling)은 API 설계에서 필수적인 품질 속성이다. API 클라이언트와 프로바이더가 서로 독립적으로 진화할 수 있도록 하는 것이 목표이다. 이를 위해 플랫폼 자율성, 시간 자율성, 형식 자율성 등의 요소를 고려하여 결합도를 최소화해야 한다.
• 수정 가능성(Modifiability): API는 진화 과정에서 유연성을 유지해야 하며, 버전 관리와 호환성을 고려해 설계해야 한다. 기존 클라이언트의 동작에 영향을 주지 않으면서도 쉽게 수정될 수 있어야 한다.
• 성능 및 규모 확장성: 네트워크 지연 시간과 대역폭 사용에 영향을 받는 클라이언트 응답 시간, 마샬링 및 언마샬링 등의 성능 문제가 중요한다. API의 처리량과 확장성은 더 많은 클라이언트를 지원하면서도 응답 시간을 저하시키지 않아야 한다.
• 데이터 간결성: 성능과 보안을 위해 API는 필요 이상으로 많은 데이터를 주고받지 않도록 설계되어야 한다. API가 진화함에 따라 불필요한 데이터가 축적될 가능성이 크기 때문에, 데이터의 간결함을 유지하는 것이 중요하다.​

이러한 요구 사항들은 API 설계 및 운영에서 필수적인 품질 속성으로 간주되며, API가 성공적으로 작동하고 진화할 수 있도록 돕는다.

사례 연구와 의사 결정 모델:

보험 회사의 서비스 통합 사례를 통해 API 사용 사례를 다룬다. API 설계에서 의사 결정을 내릴 때 고려해야 할 모델과 설계 체크리스트를 제시한다.

고급 주제:

클라우드 네이티브 API, 마이크로서비스와 같은 최신 API 설계 방식이 확장성과 독립적인 배포에 어떻게 기여하는지 설명한다. API 버전 관리 및 시간이 지남에 따라 발생하는 변경 사항을 어떻게 처리할지에 대한 전략을 설명한다. 소프트웨어 아키텍트와 개발자들이 견고하고 확장 가능하며 통합이 용이한 API를 설계하는 데 필요한 지식을 제공한다.

참고 문헌
[1]  올라프 짐머만 , 미르코 스토커 , 다니엘 뤼브케 , 우베 즈둔 , 세자레 파우타소 , "마이크로서비스 API 디자인 패턴: 쉬운 통합을 위한 결합도 최적화 전략" 에이콘. 이승범 역

크리스토퍼 알렉산더(Christopher Alexander, CA)는 오스트리아 출신의 건축가(Architect)이다. 사용자 중심의 설계 방식과 패턴 언어(Pattern Language)를 통한 건축 설계 방식으로 유명하다. 특히, 다른 건축가들과 다른 부분은 건축과 도시 설계를 보다 인간 중심적이고 살아 있는 방식으로 접근해야 하는 것을 강조했다. 이러한 접근법은 그는 여러 저서를 남겼는데,  유명한 초기 저서인 "영원의 건축"[1]이나 "패턴 랭귀지"[2] 뿐만 아니라 그의 마지막 4권의 저서인 "Nature of Order"[3] 등에서 상세히 설명한다. 이 책들에서 자연의 형태와 어울리는 건축적 원리를 제시하며, 디자인 프로세스에서 "살아 있는 구조"를 창조하는 방법에 대해 설명한다.

"영원의 건축"의 "건물군 설계하기"에서는 캘리포니아에 세워질 정신과 병원 설계에 대한 사례를 소개 한다. 이 장의 초기에 언급되어 있듯이 실재 병원의 주요 이해관계자인 병원장, 의료진, 관련 연구원들이 설계에 참여한다. 시작은 이해관계자들이 생각하는 "기능"이나 "활동"을 기반으로 적용해야 하는 패턴들을 포함시키거나 제외하는 작업들을 상당히 긴 시간의 토론을 통해 찾아간다. 이러한 패턴에 합의하게 되면 설계 준비가 되었다고 보고 설계를 시작한다. 이 때, 사무실에 설계를 하는 것이 아니라 건물이 세워질 대지에 나가서 이해 관계자들과 함께 이야기를 나누며 진행된다. 이러한 과정을 거칠 때, CA는 "눈을 감고 생각해보라"라는 요청을 많이 했다.

"Nature of Order"의 Book 2의 13.9 "The process of Finding a Good Centers"에도 비슷한 사례가 나온다. 앙드레와 애나 부분의 집 설계에 관한 부분이다. 일반적으로 부억, 거실, 식당과 같은 구조를 만들면서도 가족들은 아이들과 보낼 장소에 대한 필요가 있었던 것 같다. 가족방(family room)이 일반적인 해법이겠지만, CA는 적절한 해결책이 아니라 생각한 것 같다. 역시, 이해 관계자들과 3일간의 토론이 있었다. 눈을 감고 미소 띄운 앙드레가 떠올린 것은 프랑스 남부에 있는 그의 할아버지 집이었고 벽난로, 테이블 그리고 밖에서 들어오는 남향의 햇볕이었다. 이를 기반으로 이 집의 여러 중요 부분 중 하나인 농가의 부엌(farmerhouse kitchen)이 만들어졌다.

일본의 학교법인인 Eishin School(盈進学園, 영진학원)도 CA가 참여했고 이 과정이 "The Battle for the Life and Beauty of the Earth: A Struggle Between Two World-Systems"[4]에 담겨져 있다. 여기서도 위에서 이야기한 병원 설계와 유사하게 이해관계자들과 진행한 내용들이 담겨져 있다. 특히 8장을 보면 안드레의 사례와 비슷하게 이해 관계자들이 눈을 감고 상상하게 한다. 그런데, 이게 자신이 중요하다고 생각하는 구체적인 경험과 연결된다. 인터뷰이는 부끄러워 하기도 하고, 주저하기도 하지만 꿈같은 이야기를 꺼내게 된다. 이러한 과정을 통해 정리된 패턴 랭귀지는 수 개월에 걸처 이해관계자들에게 채택되게 된다. 이후 9개월에 걸처 부지에 직접 나아가서 병원에서의 사례와 같이 설계를 진행하는 과정을 거친다.

CA가 소프트웨어 공학에 많은 영향을 끼치기도 했고, 이러한 것들이 소프트웨어 설계에도 영향을 많이 미치고 있다고 생각된다. 위에서 CA가 사용한 방법을 보면, 이해관계자를 참여 시키는 것을 넘어 그 들에게 중요한 기능이나 활동 그리고 거기에 숨어 있는 요구 사항을 함께 찾는 것이 핵심인 것을 살펴 볼 수 있다. 이 부분을 소프트웨어 아키텍처 설계 측면에서 살펴 보면, 아키텍처 드라이버, 포스(force) 혹은 품질 속성(Quality Attribute)라는 것으로 볼 수 있다. 이런 것들을 발견하여 건축물의 "살아있는 구조"를 만들 수 있는 것처럼 소프트웨어의 "살아있는 구조"도 만들어 낼 수 있을 것으로 기대해 본다. 이러한 과정을 도와 줄 수 있는 것들이 도메인 주도 설계(DDD), Quality Attribute Workshop(QAW) 혹은 ATAM이 있다. 이러한 프로세스를 통해서 건축물을 설계할 때, 이해 관계자들과 소통하는 부분과 연결하여 이해할 수 있다.

참고문헌
[1] 크리스토퍼 알렉산더 "영원의 건축", 한진영 역, 안그라픽스 
[2] 크리스토퍼 알렉산더, 사라 이시가와, 머레이 실버스타인, "패턴 랭귀지" 이용근, 양시관, 이수빈 공역, 인사이트
[3] Christopher Alexander, "The Process of Creating Life: Nature of Order, Book 2: An Essay on the Art of Building and the Nature of the Universe", The Center for Envionmental Structure
[4] Christopher Alexander (Author), HansJoachim Neis Maggie Moore Alexander. 
"The Battle for the Life and Beauty of the Earth: A Struggle Between Two World-Systems", Center for Environmental Structure, 16 1st Edition