api-connector-builder

API Connector Builder

이 작업은 일반 HTTP 클라이언트를 만드는 것이 아니라 저장소 고유의 통합 표면을 추가하는 일일 때 사용합니다.

핵심은 호스트 저장소의 패턴에 맞추는 것입니다.

• 커넥터 레이아웃
• 설정 스키마
• 인증 모델
• 에러 처리
• 테스트 스타일
• 등록/탐지 wiring

사용 시점

• "이 프로젝트에 Jira 커넥터를 만들어줘"
• "기존 패턴에 맞춰 Slack provider를 추가해줘"
• "이 API용 새 integration을 만들어줘"
• "저장소의 connector 스타일에 맞는 plugin을 만들어줘"

가드레일

• 저장소에 이미 통합 아키텍처가 있는데 새 아키텍처를 발명하지 않습니다
• 벤더 문서만 보고 시작하지 말고 저장소 내부의 기존 커넥터부터 읽습니다
• 저장소가 registry wiring, 테스트, 문서를 기대한다면 transport 코드에서 멈추지 않습니다
• 저장소에 더 최신 패턴이 있는데 오래된 커넥터를 무비판적으로 따라하지 않습니다

워크플로

1. 저장소의 집 스타일 파악

최소 2개 이상의 기존 connector/provider를 읽고 다음을 매핑합니다.

• 파일 레이아웃
• 추상화 경계
• 설정 모델
• retry / pagination 관례
• registry hook
• 테스트 fixture와 이름 규칙

2. 대상 통합 범위 축소

저장소가 실제로 필요한 표면만 정의합니다.

• 인증 흐름
• 핵심 엔터티
• 핵심 read/write 동작
• pagination과 rate limit
• webhook 또는 polling 모델

3. 저장소 네이티브 레이어로 구축

일반적인 슬라이스:

• config/schema
• client/transport
• mapping layer
• connector/provider entrypoint
• registration
• tests

4. 원본 패턴 기준으로 검증

새 커넥터는 다른 생태계에서 가져온 것처럼 보이면 안 되고, 코드베이스 안에서 당연한 구성처럼 보여야 합니다.

참조 형태

Provider-style

providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

Connector-style

integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScript plugin-style

src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

품질 체크리스트

• 저장소 내 기존 통합 패턴과 일치한다
• config validation이 존재한다
• 인증과 에러 처리가 명시적이다
• pagination/retry 동작이 저장소 관례를 따른다
• registry/discovery wiring이 완성됐다
• 테스트가 호스트 저장소 스타일을 따른다
• 저장소가 요구하면 문서/예제도 갱신된다

관련 스킬

• backend-patterns
• mcp-server-patterns
• github-ops