API Documentation
SynapEditor API
이 페이지에서는 SynapEditor를 서비스에 연동하기 위한 핵심 API 개념과 예제를 한 번에 볼 수 있도록 3뎁스 네비게이션 구조로 정리했습니다.
Overview
전체 API 지형을 한 번에 이해하고 싶을 때 보는 개요 섹션입니다.
What is SynapEditor API?
SynapEditor API는 웹 서비스에 리치 텍스트/Office 편집 기능을 임베딩하기 위한 JavaScript/HTTP 인터페이스입니다.
Use cases
- 게시판/포털의 리치 텍스트 편집기 교체
- 그룹웨어, 이메일 작성기, 공문 시스템 등 문서 작성 화면
- LMS/CRM/사내 지식 관리 시스템의 문서 편집기
Key concepts
- Editor Runtime: 에디터 인스턴스의 생명주기를 관리하는 객체
- Document: 실제 문서 데이터(본문, 메타데이터 등)
- Plugin/Extension: 기능 확장을 위한 모듈 구조
Authentication
SynapEditor API 서버와 통신할 때는 프로젝트별 발급된 API 키를 사용합니다.
API keys
일반적으로 `x-api-key` 헤더에 프로젝트 키를 포함하여 요청합니다.
curl https://api.synapeditor.example.com/v1/documents \
-H "x-api-key: YOUR_PROJECT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "New document" }'Best practices
- API 키는 서버사이드에만 보관하고, 클라이언트에 직접 노출하지 않습니다.
- 환경변수/시크릿 매니저를 사용해 키를 관리합니다.
- 프로젝트/환경(DEV, STG, PROD) 별로 서로 다른 키를 사용합니다.
Editor Runtime
브라우저 환경에서 SynapEditor 인스턴스를 생성하고 관리하는 방법을 다룹니다.
Initialization
최소 설정으로 에디터를 초기화하는 방법부터, 고급 옵션까지 단계적으로 살펴봅니다.
Basic init
가장 단순한 초기화 예시는 다음과 같습니다.
import { createEditor } from '@synapeditor/runtime';
const editor = createEditor({
element: document.getElementById('editor-root'),
initialContent: '<p>Hello SynapEditor!</p>',
});Advanced options
플러그인, 테마, 협업 옵션 등은 고급 설정 섹션에서 다룹니다. 실제 서비스에서는 아래와 같이 옵션을 조합해 사용합니다.
const editor = createEditor({
element: document.getElementById('editor-root'),
initialContent: serverDocument,
theme: 'synap-light',
plugins: ['table', 'comment', 'ai-assistant'],
collaboration: {
roomId: 'document-123',
userId: currentUser.id,
},
});Document lifecycle
문서를 불러오고, 편집하고, 저장하는 전체 흐름을 다룹니다.
Load document
const document = await fetch('/api/documents/123').then((res) => res.json());
editor.loadDocument(document);Save document
const payload = editor.serialize();
await fetch('/api/documents/123', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});Collaboration & AI
SynapEditor의 강점인 실시간 협업과 AI 도우미 기능을 API 관점에서 정리합니다.
Real-time collaboration
WebSocket 기반의 실시간 동기화로 여러 사용자가 동시에 문서를 편집할 수 있습니다.
Presence
온라인 사용자, 커서 위치, 선택 영역 등의 프레즌스를 스트림으로 제공합니다.
Conflict resolution
충돌 해결 알고리즘(예: CRDT/OT)을 사용하여 편집 내용을 안전하게 병합합니다.
AI assistant
문서 내에서 AI 기능을 호출하는 API 형태를 설계할 수 있습니다. 예시는 다음과 같습니다.
Generate content
const selection = editor.getSelection();
const suggestion = await fetch('/api/ai/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ selection }),
}).then((res) => res.json());
editor.insertContentAtSelection(suggestion.html);Refine content
const selection = editor.getSelectionHtml();
const refined = await fetch('/api/ai/refine', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ html: selection, tone: 'professional' }),
}).then((res) => res.json());
editor.replaceSelection(refined.html);