API v2.1

BrB.kr API Docs

몇 줄의 코드로 링크 단축 기능을 서비스에 통합하세요. API Key 하나면 시작할 수 있습니다.

개요

BrB.kr API는 RESTful 방식으로 설계되었습니다. 모든 요청과 응답은 JSON 형식을 사용합니다.

기본 URL

https://brb.kr

인증

API 요청에는 API Key 인증이 필요합니다. API Key는 관리자 대시보드에서 발급받을 수 있습니다.

요청 헤더

모든 API 요청에 X-API-Key 헤더를 포함하세요.

X-API-Key: brbkr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

보안 주의사항

API Key를 클라이언트 코드에 노출하지 마세요
환경변수나 시크릿 관리 서비스를 사용하세요
API Key가 노출되면 즉시 재발급하세요

엔드포인트

POST/api/shorten

긴 URL을 단축 URL로 변환합니다.

요청

{
  "url": "https://example.com/very/long/url",
  "mode": "common",  // 선택
  "lang": "ko"       // 선택
}

Parameter	Type	Description
url *	string	단축할 원본 URL (필수)
mode	string	코드 생성 모드 (선택, API Key의 첫 번째 allowedModes 기본 적용) commonkoreantimefile

응답

{
  "success": true,
  "data": {
    "code": "Ab3xYz",
    "fullUrl": "https://brb.kr/Ab3xYz",
    "originalUrl": "https://example.com/very/long/url",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "mode": "common"
  }
}

GET/api/redirect/[code]

단축 코드의 원본 URL 정보를 조회합니다.

이 엔드포인트 호출 시 클릭 카운트가 증가합니다.

응답

{
  "success": true,
  "data": {
    "code": "Ab3xYz",
    "originalUrl": "https://example.com/very/long/url",
    "shortUrl": "https://brb.kr/Ab3xYz",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "lang": "ko",
    "stats": {
      "clicks": 1234,
      "uniqueVisitors": 892,
      "lastClickedAt": "2025-01-14T15:30:00.000Z",
      "referrers": {
        "twitter.com": 245,
        "facebook.com": 180,
        "direct": 156
      },
      "devices": {
        "mobile": 620,
        "desktop": 580,
        "tablet": 34
      },
      "browsers": {
        "Chrome": 540,
        "Safari": 380,
        "Firefox": 120
      }
    }
  }
}

통계 필드

Field	Type	Description
clicks	number	총 클릭 수
uniqueVisitors	number	순 방문자 수 (IP 기반)
lastClickedAt	string \| null	마지막 클릭 시간 (ISO 8601)
referrers	object	유입 경로별 클릭 수 (상위 5개)
devices	object	기기별 클릭 수 (mobile, desktop, tablet)
browsers	object	브라우저별 클릭 수

에러 처리

에러 발생 시 일관된 형식의 응답이 반환됩니다.

에러 응답 형식

{
  "success": false,
  "error": {
    "code": "MODE_NOT_ALLOWED",
    "message": "허용되지 않은 mode입니다.",
    "details": {
      "requestedMode": "korean",
      "allowedModes": ["common", "timefile"]
    }
  }
}

에러 코드

Code	Status	Description
INVALID_API_KEY	401	유효하지 않은 API Key
EXPIRED_API_KEY	401	만료된 API Key
REVOKED_API_KEY	403	비활성화된 API Key
INSUFFICIENT_PERMISSION	403	권한 부족
MODE_NOT_ALLOWED	403	허용되지 않은 mode
RATE_LIMIT_EXCEEDED	429	Rate limit 초과

Rate Limit

API Key마다 개별 Rate Limit이 적용됩니다. 기본값은 시간당 1,000회입니다.

응답 헤더

X-RateLimit-Limit허용된 최대 요청 수
X-RateLimit-Remaining남은 요청 수
X-RateLimit-Reset리셋 시간 (Unix timestamp)
Retry-After재시도까지 대기 시간 (초)

코드 예제

기본 사용법

const API_KEY = 'brbkr_live_xxx';

async function createShortUrl(url) {
  const response = await fetch('https://brb.kr/api/shorten', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ url }),
  });

  const data = await response.json();
  return data.data.fullUrl;
}

// Usage
const shortUrl = await createShortUrl('https://example.com/long/url');
console.log(shortUrl); // https://brb.kr/Ab3xYz

API Playground

API 플레이그라운드

직접 API를 테스트해보세요.

Request Preview

curl -X POST https://brb.kr/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url/path"}'

Response

// Response will appear here...