woowahan·2025년 12월 26일원문

끊김 없는 사용 경험을 위하여 : 카카오톡 선물함 속 교환권을 배달의민족 주문으로 연결한 여정 (새 탭에서 열림)

배달의민족 선물하기 팀은 사용자가 카카오톡으로 받은 브랜드 교환권을 배달의민족 앱에서 직접 등록하고 주문에 사용할 수 있도록 하는 '외부 교환권 연동 서비스'를 기획하고 구현했습니다. 이 프로젝트는 플랫폼 간의 기술적·비즈니스적 장벽을 허물어 사용자의 파편화된 구매 경험을 하나로 잇고, 외부의 잠재적 주문 수요를 배달의민족 생태계 안으로 흡수하는 것을 핵심 목표로 삼았습니다. 결과적으로 기술적 복잡성과 다자간의 이해관계를 극복하며 '끊김 없는 연결'이라는 사용자 중심의 가치를 실현해냈습니다. **사용자 불편 해소와 비즈니스 성장의 결합** - 카카오톡 선물을 사용하기 위해 브랜드 자사 앱을 새로 설치하거나 매장을 직접 방문해야 했던 고객의 페인포인트(Pain Point)를 해결했습니다. - 외부 플랫폼에 머물던 교환권 수요를 배달의민족 앱 내 주문으로 전환함으로써 신규 고객 유입과 락인(Lock-in) 효과를 도모했습니다. - 단순히 기능을 추가하는 것을 넘어, 플랫폼 경계를 확장하여 배달의민족을 모든 주문 경험의 통합 창구로 만들고자 했습니다. **플랫폼 간 장벽을 넘는 ‘연결’의 본질 정의** - 여러 조직이 참여하는 대규모 프로젝트에서 "플랫폼 간 장벽을 넘어 사용자에게 끊김 없는 연결을 제공한다"는 본질적인 목표를 설정하여 의사결정의 기준으로 삼았습니다. - 기술적 제약이나 비즈니스 수익성 등 이해관계가 충돌할 때마다 프로젝트의 본질을 자문하며 사용자 중심 사고를 유지했습니다. - 고립된 플랫폼 생태계를 연결함으로써 사용자에게 경험의 단절이 없는 새로운 가치를 제공하는 선례를 남겼습니다. **다자간 협업을 위한 맞춤형 소통 기술** - 카카오(플랫폼사), 브랜드사, 쿠폰 연동사 등 서로 다른 KPI를 가진 파트너들과 공통의 목표인 ‘고객 경험 개선’을 공유하며 협력을 이끌어냈습니다. - 백엔드 개발자에게는 API 응답 속도와 에러 핸들링을, 비즈니스 담당자에게는 제휴 조건과 정산 프로세스를 중심으로 설명하는 ‘맞춤형 언어’를 사용했습니다. - ‘등록·사용’(배민)과 ‘조회·승인’(연동사)처럼 서로 다른 도메인 용어와 로직을 꼼꼼히 동기화하여 시스템 간의 간극을 메웠습니다. **주도적인 문제 해결과 기술적 조율** - 단순히 요구사항을 전달하는 가교 역할을 넘어, 양사 기술팀이 합리적인 타협점을 찾을 수 있도록 API 스펙과 에러 대응 정책을 주도적으로 조율했습니다. - 다양한 외부 연동사의 시스템을 수용하면서도 배달의민족 내에서의 사용 경험을 표준화하기 위한 기술적 스펙을 정의했습니다. - 복잡한 의존 관계를 가진 작업들 사이에서 우선순위를 설정하고 일정을 관리하며 프로젝트의 항해사 역할을 수행했습니다. 이 프로젝트는 기술적 구현만큼이나 플랫폼 간의 심리적·비즈니스적 거리를 좁히는 과정이 중요함을 보여줍니다. 복잡한 시스템 연동을 앞두고 있다면, 기술 스펙에 매몰되기보다 '사용자에게 어떤 연결된 가치를 줄 것인가'라는 본질을 먼저 정의하고, 파트너의 언어로 소통하며 주도적으로 표준을 만들어가는 접근 방식이 필요합니다.

API 설계사용자 경험product-managementbackend+3

toss·2025년 11월 27일원문

토스페이먼츠의 Open API 생태계 (새 탭에서 열림)

토스페이먼츠는 Open API를 단순한 통신 수단을 넘어 수십 년간 안정적으로 운영되어야 할 핵심 인프라로 정의합니다. 20만 개 이상의 가맹점이 사용하는 환경에서 개발자의 인지 부하를 줄이고 연동 신뢰성을 높이기 위해, 리소스 중심의 인터페이스 설계와 자동화된 생태계 구축을 최우선 과제로 삼고 있습니다. 이러한 철학은 기술적 완성도를 넘어 가맹점 개발자가 겪는 전반적인 경험(DX)의 질을 결정짓는 근간이 됩니다. ### 리소스 중심의 일관된 인터페이스 설계 * **직관적인 경로 규칙**: 가맹점이 URL 구조만 보고도 기능을 예측할 수 있도록 `버전/도메인/리소스 고유 ID` 순서의 일관된 경로 체계를 사용합니다. 특정 리소스 지정 외의 조건은 쿼리 파라미터나 JSON 필드로 분리하여 명확성을 높였습니다. * **중첩 객체를 활용한 모듈화**: 카드 정보나 현금영수증 내역처럼 여러 API에서 반복되는 데이터는 JSON의 계층 구조를 활용해 객체 형태로 모듈화합니다. 이는 데이터 중복을 줄이고 응답의 의미를 명확하게 전달하며, null 체크 등 가맹점의 코드 로직을 간소화합니다. * **도메인별 객체 재사용**: 승인, 조회, 취소 등 연관된 도메인의 API들이 동일한 응답 객체를 공유하도록 설계하여, 개발자가 새로운 API를 연동할 때 추가적인 학습 없이 결과를 예측할 수 있게 합니다. * **자연어 기반 데이터 표현**: 시스템 효율을 위한 코드 값(예: SC0010) 대신 "현대", "국민"과 같은 직관적인 한글 데이터를 제공합니다. 또한 `Accept-Language` 헤더에 따라 영문 등으로 응답을 자동 전환하는 로컬라이제이션(Localization)을 지원합니다. * **표준화된 오류 처리**: HTTP 상태 코드로 큰 틀의 성공/실패를 구분하고, 상세한 에러 코드와 메시지를 담은 표준 객체를 응답 바디에 포함하여 가맹점이 상황에 맞춰 유연하게 대응할 수 있도록 돕습니다. ### 비동기 처리를 위한 안정적인 웹훅 체계 * **이벤트 기반 처리**: 즉각적인 응답이 어려운 비동기 결제 상황에서 서버가 클라이언트에 처리 완료를 알리는 웹훅 인터페이스를 API와 함께 제공합니다. * **데이터 구조의 일관성**: 웹훅을 통해 전달되는 데이터 페이로드를 일반 API 응답과 동일한 리소스 객체 구조로 설계하여 가맹점의 파싱 로직 중복을 방지합니다. * **지수 백오프(Exponential Backoff) 재전송**: 네트워크 이슈나 가맹점 서버 장애로 인한 웹훅 전송 실패 시, 수신 서비스의 회복 시간을 고려하여 점진적으로 재시도 간격을 늘리는 전략을 사용합니다. * **자가 조치 도구 제공**: 개발자가 직접 웹훅 전송 내역을 조회하고 필요 시 수동으로 재전송할 수 있는 기능을 개발자 센터를 통해 지원하여 운영 편의성을 높였습니다. ### 개발자 경험(DX) 강화를 위한 문서 자동화 * **OAS 기반 실시간 동기화**: 수동 문서 작성의 한계를 극복하기 위해 OpenAPI Specification(OAS)과 Springdoc 라이브러리를 활용하여 서버 코드와 문서가 실시간으로 동기화되는 시스템을 구축했습니다. * **문서의 신뢰성 확보**: API 스펙이 변경될 때마다 연동 문서가 즉시 업데이트되므로, 가맹점 개발자는 항상 실제 동작하는 서버와 일치하는 최신 명세를 바탕으로 안심하고 개발할 수 있습니다. 토스페이먼츠의 사례처럼 좋은 Open API는 단순히 기능의 유무를 넘어, 개발자가 '설명 없이도 이해할 수 있는' 직관적인 구조와 자동화된 지원 환경을 갖추어야 합니다. 특히 리소스 중심 설계와 API-웹훅 간 데이터 일관성은 가맹점의 연동 비용을 획기적으로 낮추는 실용적인 전략이 될 수 있습니다.

API 설계jsonrest-apideveloper-experience+4

naver·2025년 11월 19일원문

네이버 TV (새 탭에서 열림)

JVM 기반 웹 애플리케이션은 실행 초기 JIT(Just-In-Time) 컴파일러의 최적화 과정에서 발생하는 응답 지연 문제를 해결하기 위해 '웜업' 과정이 필수적입니다. 기존의 API 호출식 웜업은 데이터 오염이나 외부 시스템 부하와 같은 부작용을 초래할 수 있으나, 본 발표에서는 이를 극복하기 위해 핵심 라이브러리만을 직접 예열하는 '라이브러리 웜업' 방식을 제안합니다. 이 기술을 통해 부작용 없이 애플리케이션 배포 직후의 성능을 안정적으로 확보할 수 있습니다. **JVM 웜업의 필요성과 기존 방식의 한계** * JVM은 실행 초기에 인터프리터 방식으로 동작하다가, 반복되는 코드를 JIT 컴파일러가 네이티브 코드로 최적화하는 과정을 거치며 성능이 올라갑니다. * 이 최적화가 완료되기 전까지는 응답 시간이 길어지거나 CPU 사용량이 급증하는 현상이 발생하므로, 실제 트래픽이 들어오기 전 코드를 미리 실행하는 웜업이 필요합니다. * 기존의 API 호출 방식은 가짜 요청을 보내는 과정에서 DB 데이터 정합성을 해칠 수 있고, 외부 API 호출에 따른 불필요한 연동 부하를 발생시키는 단점이 있습니다. **라이브러리 웜업의 핵심 아이디어와 구현** * 비즈니스 로직 전체를 수행하는 대신, 애플리케이션에서 성능 비중이 크고 공통적으로 사용되는 '라이브러리 코드'만을 타겟팅하여 예열합니다. * 예를 들어 JSON 파싱, 암호화, 복잡한 수치 계산 모듈 등 JIT 컴파일 임계치(Threshold)를 넘겨야 하는 핵심 메서드들을 반복 호출하도록 설계합니다. * 애플리케이션 시작 단계(Post-Construct 등)에서 비즈니스 로직과는 독립된 웜업 코드를 실행함으로써 데이터 오염의 위험을 원천적으로 차단합니다. **성능 검증 및 실무적 이점** * 라이브러리 웜업 적용 후, 배포 초기에 발생하는 응답 속도의 '튀는 현상(Spike)'이 현저히 감소하고 전체적인 레이턴시가 안정화됨을 확인했습니다. * API 호출 방식보다 구현이 단순하고 외부 의존성이 적어 관리가 용이하며, 배포 파이프라인의 안정성을 높이는 데 기여합니다. * 다만, 모든 비즈니스 경로를 커버하지는 못하므로 성능 영향도가 높은 핵심 모듈을 선별하여 집중적으로 웜업하는 전략이 유효합니다. 빠른 스케일 아웃이 필요한 마이크로서비스 환경이나 지연 시간에 민감한 실시간 서비스라면, API 기반 웜업의 대안으로 이와 같은 라이브러리 단위의 정밀한 웜업 도입을 적극 권장합니다.

API 설계성능 최적화Javajvm+3

airbnb·2025년 9월 15일원문

Viaduct, 5년 후: (새 탭에서 열림)

에어비앤비는 자사의 데이터 중심 서비스 메시인 'Viaduct'의 5년간의 운영 성과를 공유하며, 이를 오픈소스로 공개하고 차세대 아키텍처인 'Viaduct Modern'으로의 전환을 발표했습니다. Viaduct는 중앙 집중식 스키마와 서버리스 비즈니스 로직 호스팅, 재진입(Re-entrancy) 구조를 통해 트래픽이 8배 성장하는 과정에서도 운영 효율성과 비용 선형성을 유지해 왔습니다. 이번 개편은 파편화되었던 API를 단순화하고 실행 엔진과 비즈니스 로직 사이의 추상화 경계를 강화하여, 거대해진 코드베이스의 유지보수성과 개발 생산성을 높이는 데 중점을 두었습니다. ### Viaduct의 핵심 설계 원칙 * **중앙 스키마(Central Schema):** 전사의 모든 도메인을 하나의 통합된 그래프로 연결합니다. 개발은 팀별로 분산되어 진행되지만, 사용자는 단일한 접점을 통해 모든 데이터와 기능에 접근할 수 있어 내부 요청의 75%가 Viaduct 내에서 처리됩니다. * **호스팅된 비즈니스 로직(Hosted Business Logic):** GraphQL 서버를 단순한 게이트웨이로 사용하는 대신, 비즈니스 로직을 직접 실행하는 서버리스 플랫폼으로 운영합니다. 이를 통해 개별 마이크로서비스 운영 부담을 줄이고 개발자가 로직에만 집중할 수 있는 환경을 제공합니다. * **재진입성(Re-entrancy):** Viaduct에 호스팅된 로직이 다른 로직을 호출할 때 GraphQL 프래그먼트와 쿼리를 사용하도록 설계되었습니다. 이는 대규모 코드베이스에서 직접적인 코드 의존성을 방지하고 모듈성을 유지하는 핵심 장치입니다. ### Viaduct Modern의 API 단순화 * **Tenant API의 통합:** 과거에는 기능 구현 방식이 복잡하고 파편화되어 있었으나, 이를 '노드 리졸버(Node Resolver)'와 '필드 리졸버(Field Resolver)' 두 가지 메커니즘으로 대폭 통합하여 개발자 경험을 개선했습니다. * **결정 트리 제거:** 구현 방식을 고민해야 했던 복잡한 결정 과정을 없애고, 스키마 자체의 정의에 따라 리졸버 유형이 자연스럽게 결정되도록 설계하여 학습 곡선을 낮췄습니다. ### 테넌트 모듈성과 협업 구조 * **테넌트 모듈(Tenant Module):** 스키마와 구현 코드를 팀별 소유권 단위로 묶어 관리합니다. 팀 간의 직접적인 코드 참조는 지양하고 GraphQL 인터페이스를 통해서만 소통합니다. * **선언적 데이터 의존성:** 예를 들어 '메시징 팀'이 '사용자 팀'의 타입에 새로운 필드를 추가할 때, `@Resolver` 어노테이션에 필요한 데이터 필드(예: 성, 이름)를 선언하기만 하면 됩니다. * **코드 의존성 해소:** 데이터 수요를 선언적으로 명시함으로써, 다른 팀의 내부 로직이나 데이터 소스가 무엇인지 알 필요 없이 독립적으로 기능을 확장할 수 있습니다. ### 프레임워크 계층화 및 유지보수성 * **강력한 추상화 경계:** GraphQL 실행 엔진, 테넌트 API, 애플리케이션 코드 사이의 인터페이스를 명확히 분리했습니다. 과거의 느슨했던 경계를 강화하여 서비스 로직의 중단 없이 엔진 성능을 개선하거나 라이브러리를 업데이트할 수 있는 구조를 갖췄습니다. * **운영 안정성:** 이러한 구조적 개선을 통해 개발자 수와 코드 라인 수가 급격히 증가함에도 불구하고 장애 시간을 절반으로 줄이는 성과를 거두었습니다. Viaduct는 대규모 조직에서 데이터 접근 방식을 통합하고 비즈니스 로직을 효율적으로 관리하려는 팀에게 강력한 모델을 제시합니다. 특히 마이크로서비스의 복잡도를 낮추고 싶은 조직이라면, Viaduct의 재진입 구조와 서버리스 호스팅 개념을 도입하여 개발 민첩성과 시스템 안정성을 동시에 확보하는 방향을 고려해 볼 만합니다.

API 설계분산 시스템서버리스마이크로서비스+3

datadog·2022년 9월 29일원문

Datadog을 구동하는 디자인 시스템, DRUIDS (새 탭에서 열림)

데이터독(Datadog)은 제품군이 급격히 확장됨에 따라 사용자에게 일관된 경험을 제공하고 개발 효율성을 높이기 위해 자체 디자인 시스템인 **DRUIDS**(Datadog Reusable User Interface Design System)를 구축했습니다. DRUIDS는 단순히 디자인 가이드를 제공하는 것에 그치지 않고, 수백 명의 디자이너와 엔지니어가 시스템을 쉽게 이해하고 구현하며 직접 기여할 수 있는 선순환 구조를 만드는 데 집중합니다. 결과적으로 이 시스템은 데이터독의 다양한 제품들이 하나의 통합된 플랫폼처럼 느껴지게 만드는 핵심적인 역할을 수행하고 있습니다. ### 직관적인 탐색과 맥락 파악을 돕는 도구 * **Cmd+K 퀵 내비게이션**: 플랫폼 전반에서 사용되는 퀵 내비 패턴을 문서 사이트에도 적용하여, 사용자가 원하는 컴포넌트, 아이콘, 로고 등을 검색을 통해 즉시 찾을 수 있도록 지원합니다. * **DRUIDS Loupe**: 실제 데이터독 페이지 위에서 단축키를 통해 실행되는 검사 도구로, 화면에 사용된 컴포넌트가 무엇인지 확인하고 해당 소스 코드, 피그마(Figma) 디자인, 문서 페이지로 즉시 이동할 수 있는 링크를 제공합니다. * **개발 환경과의 유기적 연결**: VS Code용 JSDoc 주석을 통해 코드 레벨에서 문서 링크를 제공하며, 소스 코드와 디자인 도구 간의 양방향 연결을 강화하여 정보의 파편화를 방지합니다. ### 코드 중심의 구현 편의성 제공 * **실시간 플레이그라운드**: 디자인 도구만으로는 표현하기 힘든 복잡한 상태와 기능을 확인하기 위해 React, TypeScript, CSS 코드를 기반으로 한 편집 가능한 예제를 제공합니다. 개발자는 여기서 속성(Props)을 변경해보고 실제 운영 환경에 적용할 코드를 즉시 복사할 수 있습니다. * **코드 샌드박스**: 개별 컴포넌트를 조합하여 라이브 프리뷰를 생성하고, 상태값이 포함된 URL을 통해 동료와 공유하거나 버그를 리포트하는 용도로 활용합니다. * **자동 생성되는 API 테이블**: 150개 이상의 컴포넌트 속성이 문서와 불일치하는 것을 방지하기 위해, 소스 코드에서 직접 속성 리스트와 설명을 추출하여 API 테이블을 자동으로 생성함으로써 신뢰할 수 있는 단일 소스(Single Source of Truth)를 유지합니다. ### 표준화된 기여 프로세스와 자동화 * **명확한 기여 가이드라인**: 성능, 접근성, 테스트, 명명 규칙 등 핵심 고려 사항을 포함한 가이드라인을 제공하여, 전사 엔지니어가 베스트 프랙티스를 유지하며 시스템을 발전시킬 수 있도록 돕습니다. * **CLI 툴링을 통한 보일러플레이트 제거**: `yarn component [name]`과 같은 명령어를 통해 유닛 테스트, 문서 예제 등 컴포넌트 생성에 필요한 기본 파일 구조를 자동으로 생성해 줍니다. 이를 통해 기여자는 단순 반복 작업 대신 설계와 성능 개선에 더 집중할 수 있습니다. 데이터독은 최근 비공개였던 DRUIDS 문서 사이트를 외부에 공개하며 자사의 UX 패턴을 공유하기 시작했습니다. 대규모 엔터프라이즈 환경에서 디자인 시스템의 성공은 단순히 아름다운 컴포넌트를 만드는 것이 아니라, 개발자와 디자이너가 시스템을 신뢰하고 손쉽게 사용할 수 있는 도구와 문화를 구축하는 데 있음을 잘 보여줍니다.

API 설계Figma사용자 경험React+4

figma·2019년 6월 10일·3분 읽기큐레이션 요약

Figma에 플러그인이 도입

Figma는 디자인 작업을 확장할 수 있는 플러그인 베타를 출시하며, 개발자들의 참여를 요청했다. 플러그인은 반복 작업 자동화, 외부 데이터 활용 등으로 디자인 워크플로를 개선할 수 있으며, 장기적으로는 커뮤니티가 만든 플러그인을 누구나 사용할 수 있도록 하는 것이 목표다. Figma는 안정성·보안·성능을 보장하기 위해 내부 API가 아닌 서드파티 전용 API를 설계했다고 강조한다. ## Figma 플랫폼에서 플러그인으로 확장 - Figma는 1년 전 HTTP 기반 Figma API를 공개해 외부 도구와의 연동을 지원했다. - 고객들은 API를 활용해 다음과 같은 워크플로를 구축했다. - Slack 명령으로 Figma 아이콘을 문서에 내보내기 - 디자인 파일 변경 사항을 개발 환경에 자동 반영하기 - SVG 아이콘 라이브러리를 효율적으로 업데이트·배포하기 - 플러그인은 기존 API 연동을 넘어 Figma 내부의 디자인 작업 과정을 직접 확장하는 다음 단계로 소개됐다. ## 플러그인으로 가능한 작업 - 반복적인 디자인 작업을 자동화할 수 있다. - 실제 데이터를 Figma 파일에 가져와 디자인에 활용할 수 있다. - 팀 구성원과 직접 만든 플러그인을 공유할 수 있다. - 웹사이트 제작 경험이 있는 개발자라면 비교적 쉽게 플러그인을 만들고 유지할 수 있도록 설계됐다. ## 안정성과 보안을 고려한 API 설계 - 플러그인이 Figma 업데이트 때마다 작동을 멈추는 문제를 방지하려 했다. - 내부 API를 그대로 공개하면 플랫폼 변경에 따라 API가 자주 바뀌고, 서드파티 개발자는 매번 코드를 수정해야 한다. - Figma는 플러그인 개발자를 위해 별도의 공식 API를 설계하고, 플러그인이 의존하는 API를 지속적으로 지원·관리하겠다고 밝혔다. - 플러그인이 Figma의 성능이나 사용자 경험을 저해하지 않도록 하는 것도 중요한 원칙으로 제시됐다. ## 플러그인 생태계의 설계 원칙 - 모든 디자이너가 쉽고 직관적으로 사용할 수 있어야 한다. - 웹사이트를 만들 수 있는 사람이라면 플러그인을 개발할 수 있어야 한다. - 인기 있는 프로그래밍 언어로 플러그인을 작성할 수 있어야 한다. - 플러그인이 Figma의 성능과 사용성을 해치지 않아야 한다. - 플러그인이 사용하는 모든 API를 Figma가 공식적으로 지원해야 한다. ## 베타 참여 대상과 운영 방식 - 기본적인 HTML과 JavaScript 지식이 있고 플러그인 아이디어가 있는 사람을 대상으로 했다. - 초기에는 참여 인원이 제한되며, 어떤 플러그인을 만들려는지에 따라 우선순위를 정했다. - 다양한 아이디어를 가진 베타 사용자가 API를 실제로 시험하고 개선 방향을 제시하도록 하는 것이 목적이었다. - 당시에는 개발자 중심의 베타였지만, 이후 코딩하지 않는 사용자도 커뮤니티 플러그인을 사용하게 될 것이라고 예고했다. 플러그인은 Figma를 단순한 디자인 도구가 아니라 개발자와 커뮤니티가 기능을 확장하는 플랫폼으로 전환하는 핵심 수단이다. 플러그인을 도입하려는 팀은 반복 업무 자동화나 실제 데이터 연동처럼 효과가 분명한 작업부터 시작하고, 공식 API의 안정성과 성능 영향을 함께 고려하는 것이 좋다.

원문 읽기(새 탭에서 열림)

API 설계JavaScript웹 개발HTML+2