아마도 수동으로는 잘 작동하지만, 팀에서 반복적인 릴리스가 필요해지는 순간 취약해지는 배포 파이프라인을 보고 계실 겁니다. 개발자가 번들을 만들고, 노트북에서 업로드하고, 대시보드를 확인하고, 채널을 이동한 뒤 채택 데이터를 기다리는 방식이죠. 소규모 프로젝트에서는 버틸 수 있을지 몰라도, 여러 앱과 환경, 배포 작업이 동일한 인프라를 공유하는 상황에서는 불필요한 리스크를 초래합니다.
유용한 공개 API 목록은 단순히 “어떤 엔드포인트가 있는가?” 이상의 답을 주어야 합니다. 인증, 리소스 식별자, 릴리스 상태, 할당량, 헤더, 재시도 및 배치 워크플로우가 어떻게 유기적으로 연결되는지 보여줘야 하죠. 이 가이드는 단순한 테스트 요청이 아닌, CI/CD 자동화를 구축하는 Capacitor 팀에 적용 가능한 패턴을 통해 Capgo API를 운영적 관점에서 다룹니다.
목차
- Capgo API 인증 이해하기
- API 자격 증명 생성하기
- 앱 관리를 위한 핵심 엔드포인트
- 릴리스 생성 및 관리
- 채널 전략 및 롤아웃 패턴
- 모니터링 및 진단 엔드포인트
- Rate Limiting 및 보안 헤더
- 자주 발생하는 API 에러 해결하기
Capgo API 인증 이해하기
첫 통합에서 가장 흔한 실수는 잘못된 credential 형식으로 유효한 요청을 보내는 것입니다. 대시보드에서 복사한 키가 자동으로 bearer token이 되는 것은 아니며, bearer token도 요청에서 Authorization header를 누락하거나 잘못된 scheme으로 보내면 쓸모가 없습니다. 이 경우 서버는 endpoint, payload 또는 app identifier를 검사하기 전에 인증 실패를 반환합니다.
먼저 현재 Capgo API 문서에서 해당 credential을 무엇이라 부르는지 확인한 뒤, 예제 요청을 그대로 재현해 보세요. 일반적인 bearer-token 요청의 authorization header 패턴은 다음과 같습니다:
Authorization: Bearer YOUR_TOKEN
로컬 테스트 시에는 credential을 환경 변수에 보관하세요. CI/CD 환경에서는 레포지토리에 커밋하거나, mobile bundle에 포함하거나, query string에 추가하는 대신 플랫폼의 secret store를 통해 주입해야 합니다. 모바일 애플리케이션에는 관리용 credential을 포함해서는 안 됩니다. 기기에 배포되는 모든 것은 결국 분석될 수 있기 때문입니다.
Identity와 Authorization 분리하기
인증(Authentication)은 요청자가 누구인지 확인하며, 권한 부여(Authorization)는 해당 사용자가 무엇을 변경할 수 있는지 결정합니다. 배포 서비스를 설계할 때는 이 두 가지를 별개의 체크 항목으로 다루어야 합니다.
개인 키는 테스트 단계에서 편리할 수 있지만, 프로덕션 자동화를 특정 개인의 계정에 종속시키는 문제가 있습니다. 조직 차원에서 작업 중단 없이 키를 회수하거나 교체할 수 있다면, 공유 파이프라인에는 팀 관리 키를 사용하는 것이 더 적합합니다. 대시보드와 권한 모델이 분리를 지원한다면 개발, 스테이징, 프로덕션 워크플로우에 각각 별도의 인증 정보를 사용하세요.
릴리스 엔드포인트를 호출하기 전에, 리스크가 낮은 읽기 작업을 먼저 테스트하세요. 다음 사항을 확인해야 합니다:
- 호스트가 올바른지: 현재 환경에 문서화된 API base URL을 사용하세요.
- 헤더가 완전한지: 필요한 인증 스킴(authorization scheme)과
AcceptJSON 응답을 위한 헤더를 포함했는지 확인하세요. - 바디 인코딩이 올바른지: 전송
Content-Type: application/json요청에 JSON이 포함된 경우에만 해당됩니다. - 스코프(scope)가 충분한지: 앱 메타데이터를 읽을 수 있는 자격 증명이라도 릴리스 생성이나 배포는 허용되지 않을 수 있습니다.
- 응답은 안전하게 기록됩니다: 상태 코드와 요청 식별자는 기록하되, 키, 토큰, 번들 내용 및 민감한 기기 데이터는 마스킹 처리합니다.
공개 API 카탈로그는 단순한 디렉터리에서 운영용 탐색 도구로 성장했습니다. ProgrammableWeb의 역사적 기록은 다음 규모를 넘어선 디렉터리를 설명합니다: 2018년 1월 기준 19,000개 API, 2017년에 2,294개의 새 API가 추가된 후 연평균 2,000개 이상이 추가되었습니다. 2014년 1월 이후입니다. 이러한 역사는 현대적인 공개 API 리스트가 단순히 URL을 찾는 것을 넘어, 엔지니어가 통합 동작을 평가할 수 있도록 도와야 하는 이유를 설명해 줍니다.
클라이언트 측 액세스 제어 고려 사항은 다음을 참조하세요: Capgo 앱 권한 패턴. 동일한 원칙이 적용됩니다. 관리 자격 증명은 신뢰할 수 있는 서버에 보관하고, 권한을 신중하게 정의하며, 인증 실패 시 원인을 쉽게 진단할 수 있도록 구성하세요.
API 자격 증명 생성하기
자격 증명 생성은 단순한 설정 단계가 아닌 액세스 관리 변경 사항으로 취급해야 합니다. 대시보드의 레이블은 변경될 수 있으므로 최신 Capgo 인터페이스와 문서를 기준으로 삼되, 전체적인 워크플로우는 동일합니다.
용도에 맞는 키 생성
조직 또는 계정 설정 영역에서 API 또는 developer-credentials 화면을 찾아 키 생성 작업을 선택하세요. 키 이름은 staging deployment pipeline이나 production release worker처럼 역할을 식별할 수 있도록 지정하세요. 팀 구성원이 바뀔 때 소유권이 불분명해질 수 있으므로 개인의 이름만으로 지정하는 것은 피해야 합니다.
해당 워크플로우에 필요한 최소한의 권한만 선택하세요. 배포 상태만 읽는 작업에 애플리케이션 삭제나 채널 변경 권한을 부여해서는 안 됩니다. 인터페이스에서 조직 수준과 앱 수준의 범위를 모두 제공한다면, 작업을 수행할 수 있는 범위 내에서 더 좁은 범위를 선택하세요.
대시보드에 표시될 때 secret 값을 복사하세요. 많은 자격 증명 시스템은 생성 시에만 전체 값을 보여줍니다. 값을 CI/CD secret manager에 저장한 다음, 값을 직접 출력하지 않고 파이프라인 내부에서 정상적으로 가져오는지 테스트하세요. 로컬 .env 파일은 개발 중에 도움이 될 수 있지만, 버전 관리에서 제외해야 하며 Capacitor 웹 디렉토리에 번들링되어서는 안 됩니다.
중단 없이 교체하기
자격 증명을 교체할 때는 겹치는 기간을 두세요. 새 키를 secret store에 추가하고, 이를 사용하는 pipeline 설정을 배포한 뒤, 부작용 없는 인증 읽기를 실행하고 나서야 기존 키를 폐기하세요. 서비스가 여러 활성 키를 지원한다면 모든 워커와 스케줄된 작업이 옮겨질 때까지 기존 값을 유지하세요.
팀 단위로 운영할 경우, 키 소유자, 용도, 환경, 생성일 및 폐기 절차를 내부 액세스 레지스터에 기록하세요. 레지스터에 secret 자체를 기록해서는 안 됩니다. 이렇게 하면 문서를 또 다른 secret 저장소로 만들지 않으면서도 사고 대응을 실무적으로 수행할 수 있습니다.
이 영국 정부 API 표준 OpenAPI 문서를 조기에 설계하고, 입력을 검증하며, 알 수 없는 속성은 거부하고, TLS 1.2 이상을 사용하며, 액세스 제어에 OAuth 2.0을 적용할 것을 권장합니다. 이러한 원칙은 API 키를 사용하는 통합 환경에서도 유용합니다. 자동화를 구축하기 전에 계약을 정의하고, 예상치 못한 입력은 거부하며, 전송 보안을 필수 요소로 취급하세요.
pipeline 저장 및 교체 패턴에는 다음을 사용하세요: Capgo CI/CD pipeline의 secret 관리 가이드.
앱 관리를 위한 핵심 엔드포인트
앱 관리는 이후의 모든 과정을 제어하는 컨트롤 플레인입니다. 릴리스 생성, 채널 할당, 번들 배포 및 진단에는 모두 안정적인 앱 식별자가 필요합니다. 흔히 하는 실수는 모든 작업에 사람이 읽기 쉬운 앱 이름을 전달하며 이것이 고유하게 유지될 것이라고 가정하는 것입니다. 앱을 한 번 식별하여 고유 식별자를 유지하고, 이후의 모든 작업에는 이 식별자를 사용하세요.
프로덕션 환경의 통합은 앱 라이프사이클을 다음 네 가지 기능 중심으로 모델링해야 합니다:
| 운영 | HTTP 의도 | 통합 관련 사항 |
|---|---|---|
| 애플리케이션 목록 조회 | GET |
페이지네이션, 조직 범위, 안정적인 식별자 |
| 애플리케이션 단일 조회 | GET |
설정 버전 및 배포 관계 |
| 설정 업데이트 | PATCH 또는 문서화된 업데이트 방식 |
부분 변경 vs 전체 교체 |
| 애플리케이션 삭제 | DELETE |
되돌릴 수 없는 작업이며 승인 및 감사 제어가 필요합니다 |
블로그 포스트나 오래된 SDK를 보고 엔드포인트 경로를 임의로 만들지 마세요. 현재 사용 가능한 머신 리더블 정의를 읽고, 해당 계약을 기반으로 타입이 지정된 클라이언트나 요청 래퍼를 생성하세요. OpenAPI Specification 은 HTTP API를 위한 프로그래밍 언어 독립적인 형식을 설명하며, 소스 code나 네트워크 트래픽을 직접 확인하지 않고도 엔드포인트, 인증, 요청 스키마, 응답 및 동작을 파악할 수 있게 해줍니다.
식별자 우선 워크플로우 구축
배포 워커는 변경(mutation)을 수행하기 전에 먼저 읽기(read)를 수행해야 합니다:
- 조직 및 애플리케이션 컨텍스트를 확인합니다.
- 앱 레코드를 가져와 해당 계정에 속해 있는지 확인합니다.
- 의도한 플랫폼 및 환경을 반환된 설정과 비교합니다.
- 작업 상태에 정식 앱 식별자를 저장합니다.
- 해당 식별자를 사용하여 릴리스 또는 설정 변경을 제출합니다.
- 나중에 폴링 및 진단을 위해 응답 식별자를 유지하세요.
이 절차는 파이프라인 변수가 이전 프로젝트를 가리켜 유효한 키가 잘못된 앱을 업데이트하는 고비용 오류를 방지합니다. 쓰기 작업을 허용하기 전에 staging 작업이 staging 앱을 대상으로 하도록 명시적인 환경 검증을 추가하세요.
API이 identifier, name, status, configuration 필드를 포함한 앱 객체를 반환하는 경우, 작업에 필요한 필드만 검증하고 관련 없는 추가 필드는 허용하는 응답 스키마를 사용하세요. 요청 시 알 수 없는 속성을 거부하면 설정 키 오타로 인한 실수를 방지할 수 있고, 응답 파싱 시 유연하게 처리하면 응답 구조가 확장되어도 클라이언트가 중단 없이 동작합니다.
롤백 설계를 위해 앱 식별자와 릴리스 식별자를 분리하세요. Capgo의 버전 관리 및 롤백 문서 는 관련 운영 참조 자료입니다. 롤백은 기억에 의존해 앱 설정을 재구성하는 것이 아니라, 검증된 상태의 릴리스 또는 채널 상태를 선택해야 합니다.
릴리스 생성 및 관리
프로덕션 릴리스는 upload 성공 후에도 실패할 수 있습니다. 아티팩트가 올바르게 저장되었더라도 프로세스가 미완료 상태이거나, 채널 할당이 되지 않았거나, 대상 기기에 업데이트가 전달되지 않았을 수 있습니다. 워크플로우를 관찰 가능한 상태 변화의 시퀀스로 취급하고, 모든 작업에 대해 영구적인 식별자와 재시도 계획을 세우세요.
릴리스 페이로드 준비
속성 이름, 요청 경로, 필수 필드에는 현재 Capgo 스키마를 사용하세요. 이름이 비슷한 엔드포인트에서 복사한 요청 본문은 일부만 수락되거나 예상치 못한 이유로 거부될 수 있습니다. 실무적으로 페이로드는 다음 세 가지 영역을 포함합니다:
- 애플리케이션 식별 정보: 관련 컨트롤 플레인 작업에서 반환된 애플리케이션 식별자입니다.
- 릴리스 메타데이터: API에서 요구하는 버전, 번들 식별자, 빌드 컨텍스트, 호환성 정보입니다.
- 배포 의도: 릴리스 작업이 지원하는 경우, 채널 또는 롤아웃 컨텍스트입니다.
전송하기 전에 번들을 검증하세요. Capacitor 빌드에 예상되는 웹 에셋이 포함되어 있는지, 버전이 CI 메타데이터와 일치하는지, 작업이 부분적으로 기록된 파일을 읽고 있지는 않은지 확인해야 합니다. API이 체크섬을 지원하는 경우 로컬 체크섬을 계산하세요. 이후 작업에서 업로드, 처리, 배포 이벤트를 연관 지을 수 있도록 빌드 URL, 커밋 참조, 서버가 발급한 릴리스 식별자를 배포 기록에 유지하세요.
안정적인 순서는 다음과 같습니다:
- 클린 워크스페이스에서 애플리케이션을 빌드합니다.
- 유닛, 통합, 플랫폼별 검사를 실행합니다.
- 문서화된 릴리스 작업을 통해 번들을 생성하거나 업로드합니다.
- 작업이 종료 상태에 도달할 때까지 반환된 operation을 폴링하거나 리소스를 해제하세요.
- 완료된 release를 대상 channel에 연결하세요.
- 프로모션 전 adoption 및 failure 신호를 확인하세요.
upload 응답은 서비스가 요청을 수락했음을 의미하며, 사용자에게 전달되었음을 보장하지 않습니다. 업데이트가 기기에 도달할지 여부는 여전히 processing status, 기기 적격성, 연결 상태 및 channel 멤버십에 따라 결정됩니다.
재시도를 안전하게 처리하기
timeout이 발생하면 서버가 요청을 거부했는지, 아니면 연결이 끊기기 전에 완료했는지 알 수 없습니다. 따라서 동일한 release를 다시 제출하면 중복되거나 충돌하는 버전이 생성될 수 있습니다. Capgo에서 지원하는 경우 idempotency key를 사용하세요. 해당 기능이 없다면, mutation을 재시도하기 전에 release metadata나 클라이언트에서 생성한 build identifier를 사용하여 조회하세요.
Batch upload에는 아이템별 상태 관리가 필요합니다. 각 앱 variant를 내구성이 있는 큐에 넣고 결과를 개별적으로 기록하세요. worker 재시도 시에는 전체 batch를 다시 실행하는 대신 완료되지 않은 아이템만 선택해야 합니다. 벌크 엔드포인트가 있는 경우, 응답에 모든 아이템에 대한 결과가 포함되어 있는지 확인하세요. 하나의 aggregate success 상태는 실패한 variant를 숨길 수 있고, 하나의 aggregate error는 완료된 작업을 가릴 수 있습니다.
운영 원칙: 서버의 release identifier를 즉시 저장한 다음, 처리 확인, channel 할당 및 진단 시 해당 identifier를 참조하세요.
Rate limit은 upload와 polling 모두에 영향을 미칩니다. API rate-limiting 가이드 할당량(quota)은 수행 중인 작업에 맞춰 설정되어야 하며, 클라이언트는 사용 가능한 헤더와 재시도(retry) 로직을 갖춰야 합니다. 릴리스 생성, 상태 폴링, 검색, 민감한 mutation 작업에 대해 각각 별도의 처리 방식을 적용하세요. upload 속도에 맞춰 재시도하는 폴링 루프는 정정 작업에 필요한 할당량을 모두 소모할 수 있습니다.
rate-limit 헤더가 반환되면 이를 읽고, 서버가 제공하는 retry 간격을 준수하며, 헤더가 없을 경우 지연 시간을 점진적으로 늘리세요. 여러 CI 워커가 동시에 재시도하지 않도록 jitter를 추가해야 합니다. 폴링은 제한을 두고 종료 상태에서 멈춰야 하며, 자격 증명과 token을 제거한 후 최종 응답 본문을 CI 로그에 포함하세요. 배포가 취소된 경우, 수행자 또는 자동화 작업, 현재 릴리스 상태, 그리고 아티팩트가 나중에 재시도할 수 있도록 유지되는지 여부를 기록하세요.
채널 전략 및 롤아웃 패턴
채널 설계는 단순한 명명 작업이 아니라 릴리스 거버넌스에 관한 결정입니다. Staging, beta, production 채널은 대상 사용자가 다르므로 서로 다른 프로모션 규칙을 가져야 합니다. 적절한 선택은 bundle의 불확실성 정도와 팀이 피드백을 얼마나 빨리 받아야 하는지에 따라 달라집니다.
| 채널 | 대상 고객 | 검증 항목 | 프로모션 결정 |
|---|---|---|---|
| Staging | 내부 기기 및 테스트 계정 | 설치, 마이그레이션, native 호환성, logs | 기술적 체크 통과 |
| Beta | 선정된 얼리 액세스 사용자 | 실제 동작, 지원 피드백, 업데이트 채택률 | 차단 수준의 회귀 오류 없음 |
| Production | 일반 사용자 | 안정성, 진단, 롤백 준비 상태 | 릴리스 소유자 승인 |
Staging 채널은 결정론적이어야 합니다. 검증된 테스트 기기나 계정을 할당하고, 채널이 임의로 변경되지 않도록 보호하며, CI가 필수 체크를 통과한 후에만 프로모션하도록 설정하세요. Beta는 프로덕션과 유사한 트래픽이 중요할 때 유용하지만, 명확한 대상 정의와 장애 보고를 위한 지원 프로세스가 필요합니다. Production은 지루할 정도로 안정적이어야 합니다. 즉, 릴리스가 이전 단계들을 모두 통과했고, 롤백 대상이 명확하며, 모니터링이 이미 연결되어 있어야 합니다.
API 워크플로우는 이러한 경계를 반영해야 합니다. 파이프라인은 릴리스를 한 번 생성하여 staging에 할당한 뒤, 검증이 끝나면 동일한 릴리스 객체를 프로모션할 수 있어야 합니다. 채널 간에 다시 빌드하는 방식은 추적성을 약화시킵니다. 팀이 테스트한 아티팩트와 사용자에게 배포된 아티팩트가 서로 다를 수 있기 때문입니다.
현재의 공개 API 생태계는 유지보수가 확장성만큼이나 왜 중요한지를 잘 보여줍니다. API 트래커 방대한 API와 개발자 리소스를 제공하지만, 공개 API 요약본에 대한 논의를 보면 금융, 정부, 의료, 머신러닝, 날씨, 교통 등 다양한 분야를 다룰 때 발생하는 유지보수 부담이 드러납니다. 채널 카탈로그도 마찬가지입니다. 오래된 항목과 불분명한 관리 주체로 인해, 방대한 리스트는 잘 관리되는 작은 리스트보다 오히려 유용성이 떨어집니다.
제어된 테스트 구현에 대한 자세한 내용은 다음을 참조하세요: 채널을 활용한 Capgo 스테이징 환경. 핵심 패턴은 모든 빌드 작업이 프로덕션에 직접 쓰도록 허용하는 대신, 채널 이동을 승인 절차를 거치는 명시적인 API 액션으로 만드는 것입니다.
모니터링 및 진단 엔드포인트
API가 성공 응답을 반환했다고 해서 배포가 완료된 것은 아닙니다. 팀이 어떤 릴리스를 디바이스가 발견하고, 다운로드하고, 설치했으며, 성공적으로 실행 중인지 설명할 수 있어야 배포가 완료된 것입니다. 이를 위해서는 릴리스 식별자, 채널 멤버십, 디바이스 레코드, 로그, 채택 데이터를 연결하는 워크플로우가 필요합니다.
배포 시스템에 상관관계 레코드를 기록하는 것부터 시작하세요. 앱 식별자, 릴리스 식별자, 채널, 커밋 참조, 빌드 메타데이터, 요청 타임스탬프, 그리고 최종 API 상태를 저장합니다. 지원 요청이 들어오면, 운영자는 비정형 CI 로그를 뒤질 필요 없이 문제가 발생한 디바이스에서 해당 채널과 릴리스로 바로 이동할 수 있어야 합니다.
집계하기 전에 범위를 좁혀 쿼리하세요
진단 엔드포인트는 대개 시간 범위, 채널, 기기, 플랫폼 또는 릴리스 필터를 지원합니다. 즉각적인 질문에 답할 수 있는 가장 좁은 범위의 필터를 사용하세요. 전체 설치 기반을 대상으로 하는 광범위한 쿼리는 속도가 느리고 해석이 어려우며, 페이지네이션이나 할당량 제한에 걸릴 가능성이 높습니다.
실무적인 조사 순서는 다음과 같습니다:
- 릴리스 뷰: 의도한 릴리스가 존재하는지, 그리고 대상 채널에 도달했는지 확인합니다.
- 채택 뷰: 대상 기기와 업데이트를 감지하거나 설치한 기기를 비교합니다.
- 실패 뷰: 릴리스, 플랫폼, 기기 클래스 및 설치 단계별로 에러를 그룹화합니다.
- 기기 뷰: 집계된 패턴에서 로컬 이슈가 의심될 때만 특정 기기의 로그를 조사합니다.
- 인시던트 뷰: 조사에 사용된 원본 응답과 쿼리 파라미터를 보존합니다.
채택률이 낮다고 해서 bundle이 깨졌다고 단정하지 마세요. 디바이스가 오프라인이거나, 채널에서 제외되었거나, 호환되지 않는 버전을 실행 중이거나, 앱의 업데이트 체크를 기다리는 중일 수 있습니다. 반대로, 다운로드 수가 높다고 해서 실행이 성공했다는 뜻도 아닙니다. API가 해당 상태를 노출한다면 discovery, download, installation, runtime health를 각각 분리해서 확인하세요.
진단 데이터를 자동화와 연결하기
스케줄링된 워커를 통해 릴리스 상태를 조회하고, 릴리스가 파이프라인 허용 시간보다 오래 비정상 상태(non-terminal state)에 머물 경우 알림을 보낼 수 있습니다. 또 다른 워커는 실패 기록을 수집하고 에러 코드를 정규화하여 배포 티켓에 첨부할 수 있습니다. 알림 페이로드는 릴리스, 채널, 필터링된 진단 쿼리 링크를 포함하여 간결하게 유지하세요.
인증 및 에러 핸들링은 엔드포인트 호출과 동일한 클라이언트 레이어에 있어야 합니다. 워커는 인증 정책에 따라 자격 증명을 갱신하거나 교체해야 하며, 권한 오류(authorization failures)를 잘못된 요청(malformed requests)과 구분하여 분류하고, 429 응답을 일반적인 서버 에러로 처리하는 대신 재시도 스케줄링을 위해 보존해야 합니다.
페이지네이션 커서나 문서화된 offset을 명시된 대로 정확히 사용하세요. 배치 진단 작업은 페이지 간 위치를 유지해야 하며 첫 페이지를 반복해서 요청하지 않도록 주의해야 합니다. 쿼리 실행 중 레코드가 변경될 수 있다면, 결과 보고서의 재현성을 위해 안정적인 시간 경계나 릴리스 필터를 사용하세요.
Rate Limiting 및 보안 헤더
프로덕션 클라이언트는 재시도 경로를 결정하기 전에 응답 헤더를 검사해야 합니다. 다음을 캡처하세요. X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After, 그리고 문서화된 모든 RateLimit-* API 클라이언트 미들웨어의 필드입니다. 이 필드들을 retry controller와 structured log에 전달하세요. 계정, 엔드포인트, 작업에 따라 달라질 수 있는 quota를 하드code하지 마세요.
사이의 구분이 용량 정보 및 재시도 지침 다음 요청을 결정합니다. remaining-count 헤더는 클라이언트가 제한에 얼마나 가까운지 보여줍니다. Retry-After 서버가 추가 시도를 허용하는 시점을 지정합니다. 해당 지침이 있으면 그대로 따르세요. 응답에 타이밍 가이드가 없으면 jitter를 포함한 bounded exponential backoff와 고정된 시도 횟수 제한을 사용하세요.
관리 영역 보호
Capgo 관리 요청은 신뢰할 수 있는 백엔드나 CI runner에서만 처리하세요. Capacitor 애플리케이션은 범위가 좁은 애플리케이션용 서비스를 호출할 수 있지만, release, channel, 조직 리소스를 수정할 수 있는 자격 증명을 받아서는 안 됩니다. TLS를 강제하고, body를 검증하며, trace와 에러 리포트에서 authorization 헤더를 제거하세요.
작업별로 별도의 제어를 적용하세요. 안전한 경우 읽기 전용 메타데이터 요청을 캐싱하거나 병합하세요. upload, export, 로그인 시도, release mutation에는 각각 별도의 제한을 두세요. API이 배치 작업을 지원하면 독립적인 메타데이터 읽기를 배치로 처리하되, 배치 하나가 1단위라고 가정하지 말고 배치의 요청 및 아이템 제한을 고려하세요. 또한 다음에서 설명하는 것처럼 동작 기반 제어는 분산된 남용 패턴을 감지하는 데도 도움이 됩니다. Rate-limiting 보안 가이드.
모든 요청에 타임아웃을 설정하고, 전송 실패와 HTTP 응답을 구분하세요. 타임아웃이 발생하면 mutation 결과가 불확실하므로, 재시도하기 전에 상태를 먼저 조회해야 합니다. 429 응답은 명시적인 서버 피드백이며, 클라이언트는 헤더를 기반으로 다음 시도 시점을 결정해야 합니다.
Capacitor 배포의 경우, App Store 규정 준수를 위한 Capgo의 API rate-limiting 가이드 가 관련 운영 참고 자료를 제공합니다. 자격 증명은 비공개로 유지하고, 서버 헤더를 준수하며, 재시도는 조용히 넘기지 말고 관찰 가능하게 하세요.
자주 발생하는 API 에러 해결하기
대부분의 실패는 인증, 유효성 검사, 스로틀링 세 그룹으로 나뉩니다. code를 변경하기 전에 어느 그룹인지 진단하세요. 응답 상태, 구조화된 에러 바디, 관련 헤더는 보통 다음 조치를 선택하기에 충분한 정보를 제공합니다.
인증 실패
일치하는 401 또는 이에 상응하는 인가 응답은 자격 증명이 누락되었거나, 형식이 잘못되었거나, 만료되었거나, 폐기되었거나, 잘못된 스킴으로 전송되었음을 의미합니다. 로컬 셸뿐 아니라 실제 CI job 내부의 환경 변수를 확인하세요. 요청에 현재 API 문서의 정확한 헤더 형식이 포함되어 있는지 확인한 다음, 읽기 전용 작업으로 자격 증명을 테스트하세요.
응답이 유효하지 않은 identity가 아니라 권한 부족을 나타낸다면, 이를 인가 문제로 다루세요. 조직 관리자에게 키의 scope, 앱 접근 권한, 환경을 검토해 달라고 요청하세요. 권한 오류를 해결하려고 광범위한 권한을 가진 개인 키를 공유하지 마세요.
잘못된 request body
Validation response는 서버가 요청을 수신했으나 구조나 값이 잘못되어 거절되었음을 의미합니다. 필수 필드, 타입, enum 값, 중첩된 객체 및 식별자를 중심으로 페이로드를 현재 스키마와 비교하세요. 서비스가 무시해주길 기대하기보다 지원되지 않는 필드는 삭제하는 것이 좋습니다.
민감 정보를 제외한 페이로드와 응답의 필드별 에러를 로그로 남기세요. CI에 스키마 검증을 추가하면 업로드가 시작되기 전에 잘못된 릴리스 메타데이터를 미리 걸러낼 수 있습니다. 부분 업데이트(partial update) 작업인 경우, 엔드포인트가 전체 교체가 아닌 patch 방식의 바디를 요구하는지 확인하세요.
Throttling과 모호한 mutation
일치하는 429 는 워커가 요청 전송을 중단하고 서버의 재시도 가이드를 따라야 함을 의미합니다. 다음을 준수하세요. Retry-After 가 포함된 경우, fallback 지연 시간을 계산할 때 jitter를 적용하여 여러 워커가 동시에 재시도하는 것을 방지해야 합니다.
upload 또는 릴리스 생성 중 타임아웃이 발생하면 즉시 다른 mutation을 제출하지 마세요. 클라이언트에서 생성한 build reference나 반환된 identifier를 사용하여 해당 작업을 조회하거나 가져오세요. identifier를 사용할 수 없다면, API의 공식 문서나 멱등성(idempotency) 메커니즘을 통해 원래 요청이 완료되었는지 확인하세요. 이를 통해 중복 릴리스를 방지하고 최종 배포 기록의 신뢰성을 확보할 수 있습니다.
Capgo는 앱 배포 리소스, 릴리스, 채널, 디바이스 및 관련 배포 워크플로우를 관리할 수 있는 공개 REST API를 제공합니다. 이를 통해 팀은 라이브 업데이트 작업을 기존 CI/CD 및 모니터링 시스템에 연결할 수 있습니다. 현재 제공되는 Capgo 문서를 검토하고, 최소 권한을 가진 테스트 자격 증명을 생성한 뒤, 프로덕션 배포를 자동화하기 전에 전체 릴리스 및 롤백 경로를 검증하세요.
