Salesforce Headless API 아키텍처는 Lightning UI를 시스템의 중심에서 걷어내고, API 계층을 통해 다른 채널이나 프론트엔드가 Salesforce 데이터와 로직에 접근하도록 재구성하는 접근입니다. 리테일 접점 3,000개 이상 규모의 멀티클라우드 환경에서는 Salesforce가 더 이상 최종 사용자 인터페이스가 아니라 백엔드 트랜잭션 엔진으로 동작하는 경우가 늘고 있습니다. 문제는 대부분의 Salesforce 조직이 여전히 Lightning 페이지, Flow 화면, Aura 컴포넌트를 중심으로 아키텍처를 설계하고, 그 위에 API를 얹는 방식으로 접근한다는 점입니다. 이 순서가 뒤집혀야 확장 가능한 구조가 나옵니다.
Headless 아키텍처가 필요해지는 시점
모바일 앱, 키오스크, 파트너 포털, IoT 디바이스가 동시에 Salesforce 데이터를 소비해야 하는 순간부터 UI 중심 설계는 병목이 됩니다. Lightning 컴포넌트는 브라우저 렌더링을 전제로 만들어져 있고, 이 전제를 벗어난 채널에서는 재사용이 거의 불가능합니다. 결국 채널마다 별도의 로직을 중복 구현하게 되고, 비즈니스 규칙이 여러 곳에 흩어지면서 유지보수 비용이 기하급수적으로 늘어납니다.
더 실질적인 문제는 성능입니다. Lightning 페이지는 메타데이터 로딩, 컴포넌트 라이프사이클, DOM 렌더링을 거치기 때문에 응답 시간이 API 직접 호출 대비 눈에 띄게 느립니다. 접점이 많은 조직에서 Salesforce Headless API 아키텍처를 도입하는 이유는 대부분 이 응답 시간 문제에서 시작합니다. External Services나 Apex REST 엔드포인트를 통해 데이터를 직접 노출하면, 클라이언트는 Salesforce의 렌더링 스택을 거치지 않고 필요한 데이터만 받아 원하는 방식으로 표현할 수 있습니다.
거버넌스 관점에서도 차이가 큽니다. UI가 로직을 감추고 있으면 어떤 시스템이 어떤 규칙에 의존하는지 파악하기 어렵습니다. Headless 구조에서는 모든 접근이 API를 통과하므로, 로직의 소유권과 버전 관리가 명확해집니다. 이는 Salesforce 거버넌스가 무너진 조직을 되살리는 과정에서 항상 확인하게 되는 지점이기도 합니다. Org 진단 초기에 API 계층이 존재하지 않으면, 시스템 간 의존성 지도를 그리는 것 자체가 불가능한 경우가 많습니다.
Headless 아키텍처의 핵심 설계 원칙
Salesforce Headless API 아키텍처를 제대로 설계하려면 먼저 데이터 소유권과 프레젠테이션 레이어를 물리적으로 분리해야 합니다. Salesforce는 트랜잭션 데이터와 비즈니스 로직의 시스템 오브 레코드로 남고, 표현 계층은 React, Vue, 네이티브 모바일 프레임워크 등 외부에서 자유롭게 구현하는 구조입니다.
[External Frontend]
|
| REST / GraphQL
v
[API Gateway / MuleSoft]
|
v
[Salesforce REST / GraphQL / Connect API / Apex REST]
|
v
[Salesforce Core + Data 360]
|
| Named Credentials + External Services (outbound)
v
[External APIs]이 구조에서 핵심은 세 가지입니다.
첫째, API 게이트웨이 레이어입니다. MuleSoft를 통해 Salesforce API 앞단에 게이트웨이를 두면, 인증, 레이트 리미팅, 버전 관리를 Salesforce 플랫폼 리밋과 분리해서 통제할 수 있습니다. 이 계층이 없으면 클라이언트마다 Salesforce API 리밋을 직접 소비하게 되고, 트래픽이 몰리는 채널 하나가 전체 시스템의 API 콜 한도를 잠식하는 상황이 발생합니다.
둘째, 인바운드 API의 역할 분리입니다. 표준 데이터 접근에는 Salesforce REST·GraphQL API를, Chatter와 Experience Cloud 중심 기능에는 Connect API를, 커스텀 비즈니스 계약에는 Apex REST를 검토합니다. External Services는 외부 UI가 Salesforce에 들어오는 진입점이 아닙니다. OpenAPI 기반 외부 기능을 Salesforce 내부에서 호출 가능한 Action으로 등록하는 아웃바운드 통합 방식입니다.
셋째, Data 360과의 연동 방식입니다. Headless 아키텍처에서 개인화가 필요한 경우, Data Streams로 외부 채널 이벤트를 수집하고 Data Graphs로 사전 조인된 프로필을 활성화하는 구조를 검토할 수 있습니다. 지연 시간은 소스, 스트리밍 방식, 계산, Identity Resolution과 활성화 대상에 따라 달라지므로 고정된 “평균 2~5분”을 설계 기준으로 사용하면 안 됩니다. 실제 경로를 측정하고 API 응답의 freshness 계약과 캐시 무효화 기준을 명시해야 합니다.
인증 계층 설계도 빠뜨릴 수 없습니다. Named Credentials와 OAuth 2.0 JWT Bearer Flow를 조합해 서버 간 인증을 처리하고, 사용자 컨텍스트가 필요한 호출에는 Connected App의 스코프를 세분화해야 합니다. 하나의 Connected App으로 모든 채널을 처리하려는 시도는 초기에는 편리하지만, 채널별 트래픽 패턴이 달라지는 순간 스코프 충돌과 세션 관리 문제로 되돌아옵니다.
대부분의 조직이 놓치는 함정
가장 흔한 실수는 Headless 전환을 UI 제거 작업으로만 이해하는 것입니다. 실제로는 API 계약(contract) 설계 작업입니다. Lightning 페이지를 걷어내는 것보다 훨씬 어려운 부분은 API 응답 스키마를 얼마나 안정적으로 버전 관리하느냐입니다. Salesforce 객체 스키마가 변경될 때마다 API 응답이 깨지는 구조라면, Headless 아키텍처는 오히려 UI 중심 구조보다 더 불안정해집니다. API 버전을 명시적으로 관리하고, 하위 호환성이 깨지는 변경은 반드시 새 버전으로 분리해야 합니다.
두 번째 함정은 거버넌스 리밋을 간과하는 것입니다. Headless 구조는 API 콜 볼륨을 급격히 늘립니다. 특히 모바일 앱처럼 폴링 방식으로 데이터를 갱신하는 채널이 붙으면, Salesforce의 API 콜 리밋과 동시성 리밋에 빠르게 도달합니다. Platform Events나 Change Data Capture를 활용한 이벤트 기반 아키텍처로 전환하지 않으면, 트래픽이 늘어날수록 API 리밋 초과로 인한 장애가 반복됩니다. 이 문제는 설계 초기에 이벤트 기반 패턴을 채택하지 않으면 나중에 되돌리기 매우 어려운 구조적 부채가 됩니다.
세 번째 함정은 테스트 전략의 부재입니다. UI 기반 시스템은 사용자가 눈으로 오류를 발견하지만, Headless 시스템은 API 계약이 깨져도 프론트엔드가 계속 렌더링을 시도하다가 사일런트 장애로 이어지는 경우가 많습니다. Apex REST 엔드포인트마다 계약 테스트를 자동화하고, CI/CD 파이프라인에 스키마 검증 단계를 포함시켜야 합니다. 이와 관련해서는 Salesforce DevOps와 CI/CD 파이프라인 설계에서 다룬 배포 전략이 Headless 환경에서 더욱 중요해집니다.
네 번째는 조직 내부의 오해입니다. Headless 전환을 추진하는 아키텍트는 이를 기술적 리팩토링으로 접근하지만, 비즈니스 부서는 여전히 Lightning 페이지 커스터마이징 요청을 계속 보냅니다. 이 두 트랙이 충돌하면 API와 UI 로직이 다시 뒤섞이는 퇴행이 일어납니다. Headless 전환은 기술 프로젝트가 아니라 거버넌스 정책 변경으로 조직 전체에 공지되어야 하며, 신규 요구사항이 API 계층을 우회하지 못하도록 승인 프로세스에 반영해야 합니다. 이 거버넌스 공백이 방치된 조직의 패턴은 Salesforce 거버넌스와 SI 의존성 문제에서 다룬 구조와 상당 부분 겹칩니다.
마지막으로, 멀티클라우드 통합 환경에서는 Headless API가 단일 시스템의 문제가 아니라 여러 클라우드 간 데이터 흐름의 교차점이 됩니다. 레거시 시스템 7개 이상에 걸쳐 데이터를 통합하는 멀티클라우드 프로젝트에서는, API 계층을 설계하기 전에 각 시스템의 데이터 소유권을 먼저 확정해야 합니다. 이 순서가 뒤바뀌면 API는 통합의 도구가 아니라 데이터 불일치를 증폭시키는 통로가 됩니다. Salesforce를 API 우선으로 재구성하려면 Data Cloud 아키텍처와 멀티클라우드 통합을 동시에 설계하는 접근이 필요하며, 이 부분은 Data Cloud · 멀티클라우드 아키텍처 설계 단계에서 함께 다뤄야 할 영역입니다.
Headless 전환을 실행하는 순서
기술적으로 올바른 순서는 UI 제거가 아니라 API 계약 정의부터 시작하는 것입니다. 먼저 모든 클라이언트가 필요로 하는 데이터와 액션을 목록화하고, 이를 Apex REST 또는 GraphQL 스키마로 문서화합니다. 그다음 각 엔드포인트의 SLA와 리밋 소비량을 산정하고, MuleSoft 게이트웨이에서 채널별 쿼터를 분리합니다.
이 단계에서 Agentforce와의 연동 가능성도 함께 검토할 가치가 있습니다. Agentforce의 Atlas Reasoning Engine이 Actions를 통해 외부 시스템과 상호작용할 때도 결국 동일한 API 계층을 재사용하게 되므로, Headless 아키텍처를 먼저 정비해두면 이후 에이전트 확장 작업의 비용이 크게 줄어듭니다. Agentforce 도입을 계획 중인 조직이라면 Headless API 설계를 선행 과제로 배치하는 것이 순서상 맞습니다.
마지막으로 기존 Lightning 페이지는 한 번에 걷어내지 않고, API 계층이 안정화된 이후 채널별로 순차적으로 대체하는 편이 리스크 관리 측면에서 안전합니다. 처음부터 UI 전체를 제거하려는 빅뱅 방식은 롤백 지점이 없어 장애 발생 시 복구 비용이 훨씬 커집니다.
핵심 정리
- Salesforce Headless API 아키텍처는 UI 제거 작업이 아니라 API 계약 설계 작업이며, 이 순서를 착각하면 전환 자체가 실패합니다.
- Data 360 활성화 지연은 구성에 따라 달라집니다. 실제 데이터 경로를 측정해 freshness 계약과 캐시 정책을 정해야 합니다.
- 외부 UI의 인바운드 Salesforce API와 External Services의 아웃바운드 호출 방향을 혼동하면 통합 책임과 보안 경계가 뒤집힙니다.
- Headless 전환은 CI/CD 계약 테스트와 이벤트 기반 아키텍처(Platform Events, CDC)를 전제로 해야 API 리밋 초과 장애를 피할 수 있습니다.
- Headless API 계층을 먼저 정비하면 이후 Agentforce Actions 확장 비용이 구조적으로 줄어듭니다.
