API 소개

rul.kr API 문서에 오신 것을 환영합니다. API 키 발급 없이 즉시 사용 가능한 공개 RESTful API입니다. URL 단축, 비밀 링크 생성, QR 코드 이미지 반환을 지원합니다.

모든 요청 본문은 application/json으로 전송합니다.
모든 응답은 JSON(또는 이미지) 형식으로 반환됩니다.
비밀 링크는 클라이언트 측 AES-256-GCM 암호화를 사용합니다.

인증 & Rate Limiting

별도의 API 키 발급 없이 즉각적인 익명 연동을 지원합니다. 단, 비정상적인 트래픽이 감지될 경우 서비스 보호를 위해 IP 기반 Rate Limiting이 자동으로 활성화됩니다.

Rate Limiting 정책

명시된 한도는 없으나, 짧은 시간 내 대량 요청 시 429 Too Many Requests가 반환될 수 있습니다. 자동화 도구 사용 시 요청 간 적절한 간격을 두는 것을 권장합니다. 일시적인 차단이며, 시간이 지나면 자동 해제됩니다.

기본 URL

https://rul.kr

모든 API 경로는 이 기본 URL을 접두사로 사용합니다. HTTP 요청은 HTTPS로 리디렉트됩니다.

오류 코드

오류 응답은 항상 { "error": "설명 문자열" } 형식의 JSON으로 반환됩니다.

HTTP 오류 코드 목록

코드	상태	설명
400	Bad Request	필수 필드 누락, 유효하지 않은 URL, 잘못된 링크 타입
404	Not Found	존재하지 않는 단축 코드
409	Conflict	이미 사용 중인 커스텀 코드
422	Unprocessable	커스텀 코드 형식 오류(4자 미만, 허용 외 문자 포함, 예약어)
429	Too Many Requests	Rate Limit 초과. 잠시 후 재시도하세요.
500	Internal Server Error	서버 내부 오류

POST /create

새로운 단축 주소를 발급합니다. 공개 링크와 비밀 링크(클라이언트 암호화)를 모두 지원합니다.

Request Body 명세

필드명	타입	설명
`url`	String Required	단축할 원본 URL. `https://` 없으면 자동 추가됩니다.
`type`	String Required	`"public"` 또는 `"private"`
`custom_code`	String Optional	공개 링크 전용 커스텀 코드. 영문·숫자·`-`·`_`, 4자 이상. 예약어 사용 불가.
`encrypted_data`	String 비밀 링크 필수	AES-256-GCM으로 암호화된 원본 URL (Base64).
`iv`	String 비밀 링크 필수	암호화에 사용된 Initialization Vector (Base64).

응답 예시 201 Created

{
  "success": true,
  "short_code": "aBcDeF",
  "short_url": "https://rul.kr/aBcDeF",
  "type": "public"
}

오류 응답 예시 409 Conflict

{
  "error": "이미 사용 중인 커스텀 코드입니다."
}

curl -X POST https://rul.kr/create \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/long/path", "type": "public"}'

import requests

res = requests.post(
    "https://rul.kr/create",
    json={
        "url": "https://example.com/long/path",
        "type": "public"
    }
)
data = res.json()
print(data["short_url"])  # https://rul.kr/aBcDeF

const res = await fetch("https://rul.kr/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/long/path",
    type: "public"
  })
});
const data = await res.json();
console.log(data.short_url); // https://rul.kr/aBcDeF

# 커스텀 코드 예시: https://rul.kr/my-link
curl -X POST https://rul.kr/create \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "type": "public", "custom_code": "my-link"}'

# custom_code 규칙:
# - 4자 이상
# - 영문, 숫자, 하이픈(-), 언더스코어(_)만 허용
# - 예약어(terms, privacy, api 등) 사용 불가

GET /api/stats/{short_code}

단축 코드의 기본 정보를 조회합니다. 비밀 링크의 원본 URL은 서버에 저장되지 않으므로 반환되지 않습니다.

Path Parameters

파라미터	타입	설명
`short_code`	String Required	조회할 단축 코드

응답 예시 200 OK

{
  "short_code": "aBcDeF",
  "type": "public",
  "created_at": "2026-05-18T14:32:00"
}

오류 응답 예시 404 Not Found

{
  "error": "링크를 찾을 수 없습니다."
}

curl https://rul.kr/api/stats/aBcDeF

import requests

res = requests.get("https://rul.kr/api/stats/aBcDeF")
data = res.json()

print(data["type"])        # "public"
print(data["created_at"])  # "2026-05-18T14:32:00"

const res = await fetch("https://rul.kr/api/stats/aBcDeF");
const data = await res.json();

console.log(data.type);        // "public"
console.log(data.created_at);  // "2026-05-18T14:32:00"

GET /api/qr

전달받은 URL을 QR 코드 PNG 이미지로 변환하여 반환합니다. 단축 URL과 결합해 오프라인 배포용 QR을 즉시 생성할 수 있습니다.

Query Parameters

파라미터	타입	설명
`url`	String Required	QR로 인코딩할 URL. URL 인코딩하여 전달하세요.

응답 포맷 200 OK

Content-Type: image/png — PNG 바이너리 스트림 반환. <img src="..."> 태그에 직접 URL로 사용할 수도 있습니다.

# 단축 URL의 QR 이미지 다운로드
curl -G https://rul.kr/api/qr \
  --data-urlencode "url=https://rul.kr/aBcDeF" \
  -o qrcode.png

import requests
from urllib.parse import quote

target = "https://rul.kr/aBcDeF"
res = requests.get(
    f"https://rul.kr/api/qr?url={quote(target)}"
)
if res.status_code == 200:
    with open("qrcode.png", "wb") as f:
        f.write(res.content)

const target = "https://rul.kr/aBcDeF";
const qrUrl = `https://rul.kr/api/qr?url=${encodeURIComponent(target)}`;

// <img> 태그에 직접 사용
document.querySelector("#qr-img").src = qrUrl;

// 또는 Blob으로 다운로드
const res = await fetch(qrUrl);
const blob = await res.blob();
const url = URL.createObjectURL(blob);
const a = Object.assign(document.createElement("a"), {
  href: url, download: "qrcode.png"
});
a.click();

리디렉션

단축 URL 접속 시 링크 타입에 따라 다르게 동작합니다.

동작 방식

링크 타입	응답	설명
공개 (`public`)	302 Found	원본 URL로 즉시 리디렉트. `X-Robots-Tag: noindex` 헤더 포함.
비밀 (`private`)	200 OK	암호화된 데이터와 함께 로더 페이지 반환. 브라우저가 URL 해시(#) 키로 클라이언트 복호화 수행.
없음	404	존재하지 않는 단축 코드.

비밀 링크의 복호화 키는 URL 해시(#fragment) 부분에만 존재하며, HTTP 요청에 포함되지 않아 서버에 전달되지 않습니다.