Twenty는 개발자 친화적으로 설계되어 있으며, 맞춤형 데이터 모델에 적합한 강력한 API를 제공합니다. 우리는 여러 통합 요구에 맞는 네 가지 고유한 API 유형을 제공합니다.
개발자 우선 접근 방식
Twenty는 귀하의 데이터 모델에 맞는 API를 특별히 생성합니다:
- 긴 ID가 필요하지 않습니다: 객체 및 필드 이름을 직접 엔드포인트에 사용합니다.
- 표준 및 사용자 정의 객체가 동등하게 처리됩니다: 내장된 객체와 동일한 API 처리를 사용자 정의 객체에도 제공합니다.
- 전용 엔드포인트: 각 객체와 필드에 자체 API 엔드포인트가 할당됩니다.
- 맞춤형 문서: 작업 공간의 데이터 모델에 맞게 특별히 생성됩니다.
맞춤형 API 문서는 API 키 생성 후 설정 → API 및 웹훅에서 확인할 수 있습니다. Twenty가 사용자 지정 데이터 모델에 맞는 API를 생성하므로, 문서는 귀하의 워크스페이스에 고유합니다.
두 가지 API 유형
Core API
/rest/ 또는 /graphql/에서 접근할 수 있습니다.
실제 레코드(데이터)로 작업합니다:
- People, Companies, Opportunities 등을 생성, 조회, 업데이트, 삭제합니다.
- 데이터를 쿼리하고 필터링합니다
- 데이터 기록의 관계를 관리합니다.
메타데이터 API
/rest/metadata/ 또는 /metadata/에서 접근할 수 있습니다.
워크스페이스와 데이터 모델 관리:
- 객체 및 필드를 생성, 수정 또는 삭제합니다.
- 작업 공간 설정을 구성합니다.
- 객체 간 관계를 정의합니다
REST와 GraphQL
코어 및 메타데이터 API는 REST와 GraphQL 형식으로 제공됩니다:
| 형식 | 사용 가능한 작업 |
|---|
| REST | CRUD, 배치 작업, 업서트 |
| GraphQL | 동일 + 배치 업서트, 한 번의 호출로 관계 쿼리 |
API 엔드포인트
| 환경 | 기본 URL |
|---|
| 클라우드 | https://api.twenty.com/ |
| 셀프 호스팅 | https://{your-domain}/ |
Authorization: Bearer YOUR_API_KEY
API 키 생성
- 설정 → API 및 웹훅으로 이동하세요
- + 키 생성을 클릭하세요
- 구성:
- 이름: 키를 설명하는 이름
- 만료 날짜: 키가 만료되는 시점
- 저장 클릭
- 즉시 복사 — 키는 한 번만 표시됩니다
API 키는 민감한 데이터에 대한 액세스를 부여합니다. 신뢰할 수 없는 서비스와 공유하지 마세요. 유출되었으면 즉시 비활성화하고 새 키를 생성하세요.
API 키에 역할 할당
보안을 강화하려면 액세스를 제한할 특정 역할을 할당하세요:
- 설정 → 역할로 이동
- 할당할 역할을 클릭하세요
- 배정 탭 열기
- API 키에서 + API 키에 할당을 클릭하세요
- API 키를 선택하세요
키가 해당 역할의 권한을 상속받습니다. 자세한 내용은 권한을 참조하세요.
API 키 관리
재생성: 설정 → API 및 웹훅 → 키 클릭 → 재생성
삭제: 설정 → API 및 웹훅 → 키 클릭 → 삭제
API 플레이그라운드
내장 플레이그라운드를 사용해 브라우저에서 직접 API를 테스트하세요 — REST와 GraphQL 모두에 대해 사용할 수 있습니다.
플레이그라운드에 액세스
- 설정 → API 및 웹훅으로 이동하세요
- API 키 생성(필수)
- 플레이그라운드를 열려면 REST API 또는 GraphQL API를 클릭하세요
얻을 수 있는 내용
- 대화형 문서: 귀하의 특정 데이터 모델에 맞게 생성됩니다
- 워크스페이스를 대상으로 실제 API 호출을 실행합니다
- 스키마 탐색기: 사용 가능한 객체, 필드 및 관계를 탐색합니다
- 요청 빌더: 자동 완성을 통해 쿼리를 구성합니다
플레이그라운드는 사용자 지정 객체와 필드를 반영하므로 문서는 항상 워크스페이스에 대해 정확합니다.
배치 작업
REST와 GraphQL 모두 배치 작업을 지원합니다:
- 배치 크기: 요청당 최대 60개의 기록
- 작업: 여러 기록을 생성, 업데이트, 삭제합니다
GraphQL 전용 기능:
- 배치 업서트: 한 번의 호출로 생성하거나 업데이트합니다
- 복수형 객체 이름을 사용하세요(예:
CreateCompanies 대신 CreateCompany)
속도 제한
플랫폼 안정성을 위해 API 요청에는 제한이 적용됩니다:
| 제한 | 값 |
|---|
| 요청 | 분당 100회 호출 |
| 배치 크기 | 호출당 기록 60개 |
처리량을 극대화하려면 배치 작업을 사용하세요 — 개별 요청 대신 단일 API 호출로 최대 60개의 기록을 처리할 수 있습니다.
