148 lines
5.5 KiB
Plaintext
148 lines
5.5 KiB
Plaintext
---
|
|
title: API
|
|
description: REST 또는 GraphQL을 사용해 프로그래밍 방식으로 CRM 데이터를 쿼리하고 수정하세요.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
Twenty는 개발자 친화적으로 설계되어 있으며, 맞춤형 데이터 모델에 적합한 강력한 API를 제공합니다. 우리는 여러 통합 요구에 맞는 네 가지 고유한 API 유형을 제공합니다.
|
|
|
|
## 개발자 우선 접근 방식
|
|
|
|
Twenty는 귀하의 데이터 모델에 맞는 API를 특별히 생성합니다:
|
|
|
|
* **긴 ID가 필요하지 않습니다**: 객체 및 필드 이름을 직접 엔드포인트에 사용합니다.
|
|
* **표준 및 사용자 정의 객체가 동등하게 처리됩니다**: 내장된 객체와 동일한 API 처리를 사용자 정의 객체에도 제공합니다.
|
|
* **전용 엔드포인트**: 각 객체와 필드에 자체 API 엔드포인트가 할당됩니다.
|
|
* **맞춤형 문서**: 작업 공간의 데이터 모델에 맞게 특별히 생성됩니다.
|
|
|
|
<Note>
|
|
맞춤형 API 문서는 API 키 생성 후 **설정 → API 및 웹훅**에서 확인할 수 있습니다. Twenty가 사용자 지정 데이터 모델에 맞는 API를 생성하므로, 문서는 귀하의 워크스페이스에 고유합니다.
|
|
</Note>
|
|
|
|
## 두 가지 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}/` |
|
|
|
|
## 인증
|
|
|
|
모든 API 요청에는 헤더에 API 키가 필요합니다:
|
|
|
|
```
|
|
Authorization: Bearer YOUR_API_KEY
|
|
```
|
|
|
|
### API 키 생성
|
|
|
|
1. **설정 → API 및 웹훅**으로 이동하세요
|
|
2. **+ 키 생성**을 클릭하세요
|
|
3. 구성:
|
|
* **이름**: 키를 설명하는 이름
|
|
* **만료 날짜**: 키가 만료되는 시점
|
|
4. **저장** 클릭
|
|
5. **즉시 복사** — 키는 한 번만 표시됩니다
|
|
|
|
<VimeoEmbed videoId="928786722" title="API 키 생성" />
|
|
|
|
<Warning>
|
|
API 키는 민감한 데이터에 대한 액세스를 부여합니다. 신뢰할 수 없는 서비스와 공유하지 마세요. 유출되었으면 즉시 비활성화하고 새 키를 생성하세요.
|
|
</Warning>
|
|
|
|
### API 키에 역할 할당
|
|
|
|
보안을 강화하려면 액세스를 제한할 특정 역할을 할당하세요:
|
|
|
|
1. **설정 → 역할**로 이동
|
|
2. 할당할 역할을 클릭하세요
|
|
3. **배정** 탭 열기
|
|
4. **API 키**에서 **+ API 키에 할당**을 클릭하세요
|
|
5. API 키를 선택하세요
|
|
|
|
키가 해당 역할의 권한을 상속받습니다. 자세한 내용은 [권한](/l/ko/user-guide/permissions-access/capabilities/permissions)을 참조하세요.
|
|
|
|
### API 키 관리
|
|
|
|
**재생성**: 설정 → API 및 웹훅 → 키 클릭 → **재생성**
|
|
|
|
**삭제**: 설정 → API 및 웹훅 → 키 클릭 → **삭제**
|
|
|
|
## API 플레이그라운드
|
|
|
|
내장 플레이그라운드를 사용해 브라우저에서 직접 API를 테스트하세요 — **REST**와 **GraphQL** 모두에 대해 사용할 수 있습니다.
|
|
|
|
### 플레이그라운드에 액세스
|
|
|
|
1. **설정 → API 및 웹훅**으로 이동하세요
|
|
2. API 키 생성(필수)
|
|
3. 플레이그라운드를 열려면 **REST API** 또는 **GraphQL API**를 클릭하세요
|
|
|
|
### 얻을 수 있는 내용
|
|
|
|
* **대화형 문서**: 귀하의 특정 데이터 모델에 맞게 생성됩니다
|
|
* 워크스페이스를 대상으로 실제 API 호출을 실행합니다
|
|
* **스키마 탐색기**: 사용 가능한 객체, 필드 및 관계를 탐색합니다
|
|
* **요청 빌더**: 자동 완성을 통해 쿼리를 구성합니다
|
|
|
|
플레이그라운드는 사용자 지정 객체와 필드를 반영하므로 문서는 항상 워크스페이스에 대해 정확합니다.
|
|
|
|
## 배치 작업
|
|
|
|
REST와 GraphQL 모두 배치 작업을 지원합니다:
|
|
|
|
* **배치 크기**: 요청당 최대 60개의 기록
|
|
* **작업**: 여러 기록을 생성, 업데이트, 삭제합니다
|
|
|
|
**GraphQL 전용 기능:**
|
|
|
|
* **배치 업서트**: 한 번의 호출로 생성하거나 업데이트합니다
|
|
* 복수형 객체 이름을 사용하세요(예: `CreateCompanies` 대신 `CreateCompany`)
|
|
|
|
## 속도 제한
|
|
|
|
플랫폼 안정성을 위해 API 요청에는 제한이 적용됩니다:
|
|
|
|
| 제한 | 값 |
|
|
| --------- | ---------- |
|
|
| **요청** | 분당 100회 호출 |
|
|
| **배치 크기** | 호출당 기록 60개 |
|
|
|
|
<Tip>
|
|
처리량을 극대화하려면 배치 작업을 사용하세요 — 개별 요청 대신 단일 API 호출로 최대 60개의 기록을 처리할 수 있습니다.
|
|
</Tip>
|