API 소개

Rul.kr API에 오신 것을 환영합니다! 이 문서는 Rul.kr의 URL 단축 기능을 애플리케이션에 통합하는 방법을 안내합니다. 저희 API는 단순함과 강력한 보안을 핵심 가치로 삼으며, RESTful 원칙을 준수합니다.

인증

Rul.kr API는 별도의 API 키나 인증 토큰을 요구하지 않습니다. 모든 엔드포인트는 공개적으로 접근 가능합니다. 비정상적인 요청이 감지될 경우 IP 기반의 Rate Limiting이 적용될 수 있습니다.

모든 API 요청의 기본 URL:

https://rul.kr

API 요청이 실패할 경우, 표준 HTTP 상태 코드와 함께 오류 메시지를 담은 JSON 객체를 반환합니다.

{
  "error": "오류에 대한 설명이 여기에 표시됩니다."
}

POST /create

새로운 단축 링크(공개 또는 비밀)를 생성합니다. 요청 본문은 Content-Type: application/json 형식이어야 합니다.

Request Body

필드명	타입	설명	필수
`url`	String	단축할 원본 URL. 프로토콜이 없으면 `https://`가 자동으로 추가됩니다.	필수
`type`	String	`"public"` 또는 `"private"` 중 하나	필수
`custom_code`	String	(공개 링크 전용) 사용자 지정 단축 코드. 4자 이상, 영문/숫자/-/_ 허용.	선택
`encrypted_data`	String	(비밀 링크 전용) 클라이언트 측에서 AES-256-GCM으로 암호화된 URL 데이터 (Base64)	비밀 필수
`iv`	String	(비밀 링크 전용) 암호화에 사용된 초기화 벡터 (Base64)	비밀 필수

1. 공개 링크 (랜덤 코드)

{
  "url": "https://www.google.com/search?q=url+shortener",
  "type": "public"
}

2. 공개 링크 (사용자 지정 코드)

{
  "url": "https://my-blog.com/my-post",
  "type": "public",
  "custom_code": "my-blog"
}

3. 비밀 링크

{
  "url": "ORIGINAL_URL (암호화 전에 클라이언트에서 처리)",
  "type": "private",
  "encrypted_data": "U2FsdGVkX1+...base64string",
  "iv": "someBase64IvString"
}

● 201 Created

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

● 400 Bad Request

{ "error": "커스텀 코드는 4글자 이상이어야 합니다." }

● 409 Conflict

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

GET /api/stats/{short_code}

지정된 단축 코드에 대한 메타데이터를 조회합니다.

Path Parameters

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

curl https://rul.kr/api/stats/my-blog

● 200 OK

{
  "short_code": "my-blog",
  "type": "public",
  "created_at": "2026-02-21 12:30:00"
}

● 404 Not Found

{ "error": "링크를 찾지 못 했습니다." }

GET /{short_code}

사용자를 최종 목적지로 이동시키는 경로입니다. API 엔드포인트가 아니라 브라우저 접근용입니다.

공개 링크: 서버가 302 Found로 원본 URL을 향해 즉시 리디렉션합니다.
비밀 링크: 서버는 loader.html을 반환하고, 브라우저 JavaScript가 URL 해시의 키로 복호화 후 이동합니다. 서버는 원본 URL을 전혀 알 수 없습니다.

● 404 Not Found

존재하지 않는 코드 접근 시 메인 페이지로 이동합니다.