제4장: API 인터페이스

1. WIA-LANG API 개요

WIA-LANG-001 API는 RESTful 아키텍처를 기반으로 하는 개방형 언어 보존 인터페이스입니다. 이 API를 통해 개발자는 멸종위기 언어 데이터에 접근하고, 새로운 데이터를 추가하며, 언어 분석 도구를 통합할 수 있습니다. 모든 엔드포인트는 HTTPS를 통해 보호되며, OAuth 2.0 인증을 지원합니다.

1.1 API 설계 원칙

• RESTful 설계: 직관적인 URL 구조와 HTTP 메서드 활용
• 버전 관리: URL 경로에 버전 포함 (예: /v1/languages)
• JSON 응답: 모든 응답은 JSON 형식으로 반환
• 페이지네이션: 대용량 데이터 효율적 처리
• 오류 처리: 명확한 HTTP 상태 코드와 오류 메시지
• CORS 지원: 크로스 오리진 요청 허용
• 속도 제한: 공정한 리소스 사용을 위한 Rate Limiting

2. 인증 및 권한 관리

WIA-LANG API는 OAuth 2.0 프로토콜을 사용하여 안전한 인증을 제공합니다. 弘益人間 정신에 따라 읽기 API는 무료로 공개되며, 쓰기 작업은 인증이 필요합니다.

2.1 API 키 발급 및 사용

// API 키 발급 (개발자 포털에서 발급)
const WIA_API_KEY = 'wia_lang_key_abc123def456';
const WIA_API_SECRET = 'secret_xyz789';

// API 클라이언트 초기화
import { WIALangClient } from '@wia/lang-client';

const client = new WIALangClient({
  apiKey: WIA_API_KEY,
  apiSecret: WIA_API_SECRET,
  baseUrl: 'https://api.wia.org/v1',
  philosophy: '弘益人間'
});

// OAuth 2.0 인증 토큰 발급
const authResponse = await client.authenticate();
console.log('Access Token:', authResponse.accessToken);
console.log('Expires In:', authResponse.expiresIn);

// 인증된 요청 예제
const languages = await client.getLanguages({
  endangermentLevel: 'critically_endangered',
  limit: 10
});

2.2 권한 레벨

권한 레벨	설명	허용 작업	요청 제한
Public	인증 불필요	읽기 전용 (GET)	100 req/hour
Contributor	커뮤니티 기여자	데이터 추가, 수정 제안	1,000 req/hour
Linguist	언어학자	검증된 데이터 입력	5,000 req/hour
Administrator	시스템 관리자	모든 작업 (삭제 포함)	무제한

3. 핵심 API 엔드포인트

3.1 언어 조회 및 검색

// 요청 예제
GET https://api.wia.org/v1/languages?page=1&limit=20&endangermentLevel=critically_endangered

// 쿼리 파라미터
{
  "page": 1,                              // 페이지 번호 (기본값: 1)
  "limit": 20,                            // 페이지당 항목 수 (기본값: 20, 최대: 100)
  "endangermentLevel": "critically_endangered",  // 멸종위기 등급 필터
  "region": "Asia",                       // 지역 필터
  "hasAudio": true,                       // 오디오 데이터 존재 여부
  "sortBy": "speakerCount",               // 정렬 기준
  "sortOrder": "desc"                     // 정렬 방향 (asc/desc)
}

// 응답 예제
{
  "status": "success",
  "data": {
    "languages": [
      {
        "id": "lang-jje-001",
        "code": "jje",
        "name": "제주어",
        "englishName": "Jeju Language",
        "endangermentLevel": "critically_endangered",
        "speakerCount": 5000,
        "region": {
          "country": "대한민국",
          "province": "제주특별자치도"
        },
        "lastUpdated": "2025-12-29T12:00:00Z",
        "dataQuality": {
          "completeness": 85,
          "hasAudio": true,
          "hasGrammar": true,
          "lexiconSize": 2500
        },
        "links": {
          "self": "https://api.wia.org/v1/languages/lang-jje-001",
          "lexicon": "https://api.wia.org/v1/languages/lang-jje-001/lexicon",
          "audio": "https://api.wia.org/v1/languages/lang-jje-001/audio"
        }
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 15,
      "totalItems": 300,
      "itemsPerPage": 20,
      "hasNext": true,
      "hasPrevious": false
    }
  },
  "meta": {
    "philosophy": "弘益人間",
    "version": "1.0",
    "timestamp": "2025-12-29T14:30:00Z"
  }
}

// 요청 예제
GET https://api.wia.org/v1/languages/lang-jje-001

// 응답 예제
{
  "status": "success",
  "data": {
    "id": "lang-jje-001",
    "wiaLangVersion": "1.0",
    "metadata": {
      "languageCode": "jje",
      "languageName": "제주어",
      "englishName": "Jeju Language",
      "alternativeNames": ["Jejueo", "Cheju"],
      "endangermentLevel": "critically_endangered",
      "speakerCount": 5000,
      "region": {
        "country": "대한민국",
        "province": "제주특별자치도",
        "coordinates": {
          "latitude": 33.4996,
          "longitude": 126.5312
        }
      },
      "contributors": [
        {
          "name": "강영봉",
          "role": "언어학자",
          "affiliation": "제주대학교 국어문화원",
          "contributionCount": 1250
        }
      ],
      "license": "CC-BY-SA-4.0",
      "philosophy": "弘益人間"
    },
    "statistics": {
      "lexiconSize": 2500,
      "audioRecordings": 1800,
      "videoRecordings": 150,
      "documentCount": 320,
      "lastActivity": "2025-12-28T18:45:00Z"
    }
  }
}

3.2 어휘 데이터 관리

// 요청 예제
GET https://api.wia.org/v1/languages/lang-jje-001/lexicon?search=하르방&hasAudio=true

// 응답 예제
{
  "status": "success",
  "data": {
    "languageId": "lang-jje-001",
    "languageName": "제주어",
    "words": [
      {
        "id": "word-jje-001",
        "lemma": "하르방",
        "translation": "할아버지",
        "englishTranslation": "grandfather",
        "partOfSpeech": "noun",
        "pronunciation": {
          "ipa": "haɾɯbaŋ",
          "romanization": "hareubang"
        },
        "audio": {
          "url": "https://cdn.wia.org/audio/jje/001.mp3",
          "duration": 1.2,
          "speaker": "speaker-042"
        },
        "usageFrequency": "common",
        "culturalSignificance": "high",
        "createdAt": "2025-11-15T10:20:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalItems": 2500
    }
  }
}

// 요청 예제
POST https://api.wia.org/v1/languages/lang-jje-001/lexicon
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "lemma": "고망",
  "translation": "고맙다",
  "englishTranslation": "thank you",
  "partOfSpeech": "adjective",
  "pronunciation": {
    "ipa": "komaŋ",
    "romanization": "gomang"
  },
  "semantics": {
    "definition": "감사함을 표현하는 제주어",
    "culturalContext": "일상 대화에서 자주 사용",
    "examples": [
      {
        "sentence": "고망수다",
        "translation": "고맙습니다"
      }
    ]
  },
  "contributor": {
    "name": "김제주",
    "email": "jeju@example.com"
  },
  "philosophy": "弘益人間"
}

// 응답 예제
{
  "status": "success",
  "data": {
    "id": "word-jje-2501",
    "lemma": "고망",
    "status": "pending_review",
    "message": "어휘 항목이 성공적으로 제출되었습니다. 언어학자 검토 후 승인됩니다.",
    "reviewUrl": "https://api.wia.org/v1/reviews/word-jje-2501"
  },
  "meta": {
    "philosophy": "弘益人間 - 커뮤니티 기여에 감사드립니다"
  }
}

3.3 오디오 데이터 관리

// 멀티파트 폼 데이터로 업로드
POST https://api.wia.org/v1/languages/lang-jje-001/audio
Authorization: Bearer {access_token}
Content-Type: multipart/form-data

{
  "file": [오디오 파일 바이너리],
  "wordId": "word-jje-001",
  "speaker": {
    "id": "speaker-042",
    "age": 68,
    "gender": "female",
    "nativeSpeaker": true,
    "dialectRegion": "서귀포"
  },
  "transcription": {
    "orthographic": "하르방",
    "ipa": "haɾɯbaŋ",
    "notes": "자연스러운 발음"
  },
  "recordingInfo": {
    "date": "2025-12-29",
    "equipment": "Zoom H6",
    "environment": "controlled_studio"
  }
}

// 응답 예제
{
  "status": "success",
  "data": {
    "audioId": "audio-jje-1801",
    "url": "https://cdn.wia.org/audio/jje/1801.flac",
    "format": "FLAC",
    "duration": 1.2,
    "fileSize": 245000,
    "checksum": "sha256:abc123...",
    "processingStatus": "completed",
    "waveformUrl": "https://cdn.wia.org/waveform/jje/1801.png"
  }
}

4. 고급 API 기능

4.1 언어 분석 API

// 요청 예제
POST https://api.wia.org/v1/analyze/text
Content-Type: application/json

{
  "text": "하르방이 말씀하시다",
  "sourceLanguage": "jje",
  "targetLanguage": "ko",
  "analysisType": ["morphology", "translation", "pronunciation"],
  "includeAudio": true
}

// 응답 예제
{
  "status": "success",
  "data": {
    "sourceText": "하르방이 말씀하시다",
    "detectedLanguage": "jje",
    "morphology": [
      {
        "word": "하르방",
        "lemma": "하르방",
        "pos": "noun",
        "meaning": "할아버지"
      },
      {
        "word": "이",
        "lemma": "이",
        "pos": "particle",
        "function": "subject_marker"
      },
      {
        "word": "말씀하시다",
        "lemma": "말씀하다",
        "pos": "verb",
        "honorific": true
      }
    ],
    "translation": {
      "ko": "할아버지가 말씀하시다",
      "en": "Grandfather is speaking"
    },
    "pronunciation": {
      "ipa": "haɾɯbaŋi malssɯmhasida",
      "audioUrl": "https://api.wia.org/tts/jje?text=하르방이+말씀하시다"
    }
  }
}

4.2 통계 및 대시보드 API

// 응답 예제
{
  "status": "success",
  "data": {
    "totalLanguages": 7168,
    "endangeredLanguages": 3018,
    "criticallyEndangered": 578,
    "totalWords": 15420000,
    "audioRecordings": 8920000,
    "contributors": 45230,
    "countriesCovered": 195,
    "byRegion": {
      "Asia": 3521,
      "Africa": 2139,
      "Americas": 1062,
      "Pacific": 1313,
      "Europe": 133
    },
    "recentActivity": {
      "newLanguages": 12,
      "newWords": 8450,
      "newAudio": 2340,
      "period": "last_30_days"
    },
    "philosophy": "弘益人間 - 함께 보존하는 인류의 언어 유산"
  }
}

5. 에러 처리 및 상태 코드

WIA-LANG API는 표준 HTTP 상태 코드를 사용하여 요청의 성공 또는 실패를 나타냅니다.

상태 코드	설명	예시 상황
200 OK	요청 성공	데이터 조회 성공
201 Created	리소스 생성 성공	새 어휘 항목 추가
400 Bad Request	잘못된 요청	필수 필드 누락
401 Unauthorized	인증 실패	유효하지 않은 API 키
403 Forbidden	권한 없음	관리자 전용 작업
404 Not Found	리소스 없음	존재하지 않는 언어 ID
429 Too Many Requests	요청 한도 초과	Rate Limit 도달
500 Internal Server Error	서버 오류	예상치 못한 서버 문제

5.1 에러 응답 형식

// 에러 응답 예제
{
  "status": "error",
  "error": {
    "code": "INVALID_LANGUAGE_CODE",
    "message": "제공된 언어 코드가 ISO 639-3 표준에 맞지 않습니다",
    "details": {
      "field": "languageCode",
      "value": "invalid",
      "expected": "3-letter ISO 639-3 code"
    },
    "documentation": "https://docs.wia.org/api/errors#INVALID_LANGUAGE_CODE"
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2025-12-29T14:30:00Z"
  }
}

6. SDK 및 클라이언트 라이브러리

WIA-LANG API는 다양한 프로그래밍 언어로 작성된 공식 SDK를 제공합니다.

6.1 JavaScript/TypeScript SDK

// 설치
npm install @wia/lang-client

// 사용 예제
import { WIALangClient, EndangermentLevel } from '@wia/lang-client';

const client = new WIALangClient({
  apiKey: process.env.WIA_API_KEY,
  philosophy: '弘益人間'
});

// 타입 안전 언어 조회
const languages = await client.languages.list({
  endangermentLevel: EndangermentLevel.CriticallyEndangered,
  region: 'Asia',
  hasAudio: true,
  page: 1,
  limit: 20
});

console.log(`발견된 언어: ${languages.data.length}`);

for (const lang of languages.data) {
  console.log(`${lang.name} (${lang.code}): ${lang.speakerCount}명`);

  // 어휘 조회
  const lexicon = await client.lexicon.list(lang.id, {
    limit: 10
  });

  console.log(`  어휘 항목: ${lexicon.pagination.totalItems}개`);
}

// 새 어휘 추가
const newWord = await client.lexicon.create('lang-jje-001', {
  lemma: '바당',
  translation: '바다',
  englishTranslation: 'sea',
  partOfSpeech: 'noun',
  pronunciation: {
    ipa: 'padaŋ'
  }
});

console.log(`새 단어 추가됨: ${newWord.id}`);

6.2 Python SDK

# 설치
pip install wia-lang-client

# 사용 예제
from wia_lang import WIALangClient, EndangermentLevel

client = WIALangClient(
    api_key='your_api_key',
    philosophy='弘益人間'
)

# 언어 조회
languages = client.languages.list(
    endangerment_level=EndangermentLevel.CRITICALLY_ENDANGERED,
    region='Asia',
    has_audio=True,
    page=1,
    limit=20
)

print(f"발견된 언어: {len(languages.data)}")

for lang in languages.data:
    print(f"{lang.name} ({lang.code}): {lang.speaker_count}명")

    # 어휘 조회
    lexicon = client.lexicon.list(lang.id, limit=10)
    print(f"  어휘 항목: {lexicon.pagination.total_items}개")

# 오디오 업로드
with open('recording.flac', 'rb') as audio_file:
    result = client.audio.upload(
        language_id='lang-jje-001',
        word_id='word-jje-001',
        file=audio_file,
        speaker={
            'age': 68,
            'gender': 'female',
            'native_speaker': True
        }
    )

print(f"오디오 업로드 완료: {result.url}")

7. 웹훅 및 실시간 알림

WIA-LANG API는 웹훅을 통해 실시간 이벤트 알림을 제공합니다.

7.1 웹훅 이벤트 유형

• language.created - 새 언어 추가됨
• word.created - 새 어휘 추가됨
• word.approved - 어휘 검토 승인됨
• audio.uploaded - 오디오 업로드 완료
• language.status_changed - 멸종위기 등급 변경

// 웹훅 페이로드 예제
{
  "event": "word.created",
  "timestamp": "2025-12-29T14:30:00Z",
  "data": {
    "wordId": "word-jje-2501",
    "languageId": "lang-jje-001",
    "lemma": "고망",
    "contributor": "김제주",
    "status": "pending_review"
  },
  "philosophy": "弘益人間"
}