Main Site

API 연동 튜토리얼

1. API Key 발급

외부 시스템에서 MetaCivia API를 사용하려면 API Key가 필요합니다.

  1. Architect에게 API Key 발급 요청
  2. 또는 Cloudflare 환경 변수에서 설정

2. 기본 사용법

시민 상태 조회

const response = await fetch('https://metacivia-backend.pages.dev/api/citizen/status', {
  headers: {
    'X-Wallet-Address': '0x1234567890123456789012345678901234567890123456789012345678901234'
  }
})

const data = await response.json()
console.log(data)
// {
//   wallet: "0x...",
//   status: "citizen",
//   rank: 2,
//   civicCredit: 500,
//   influence: 25.5
// }

외부 API 사용 (API Key 필요)

const response = await fetch('https://metacivia-backend.pages.dev/api/external/citizen/0x.../credit', {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
})

const data = await response.json()
console.log(data)

3. Webhook 설정

이벤트를 실시간으로 수신하려면 Webhook을 설정합니다.

await fetch('https://metacivia-backend.pages.dev/api/external/webhook', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-webhook-url.com/events',
    events: ['citizen_minted', 'ritual_completed', 'rank_up']
  })
})

Webhook 이벤트 형식

{
  "type": "citizen_minted",
  "data": {
    "walletAddress": "0x...",
    "status": "observer"
  },
  "timestamp": 1234567890
}

4. Rate Limiting

API는 Rate Limiting이 적용됩니다:

  • 기본 제한: 100 requests/minute per API key or IP
  • 초과 시: 429 Too Many Requests 응답

Rate Limit 처리 예제

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options)
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
      continue
    }
    
    return response
  }
  throw new Error('Max retries exceeded')
}

5. 에러 처리

try {
  const response = await fetch(url, options)
  
  if (!response.ok) {
    const error = await response.json()
    console.error('API Error:', error.error)
    
    switch (response.status) {
      case 400:
        console.error('Bad Request')
        break
      case 401:
        console.error('Unauthorized - Check API Key')
        break
      case 403:
        console.error('Forbidden - Insufficient permissions')
        break
      case 429:
        console.error('Rate Limited')
        break
      default:
        console.error('Server Error')
    }
  }
  
  const data = await response.json()
  return data
} catch (error) {
  console.error('Network Error:', error)
  throw error
}

다음 단계