API 소개

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

주요 기능은 다음과 같습니다:

• 공개 링크 생성: 일반적인 단축 링크를 생성합니다. 기억하기 쉬운 사용자 지정 코드를 사용할 수 있습니다.
• 비밀 링크 생성: 원본 URL을 클라이언트 측에서 암호화하여 서버조차 내용을 알 수 없는 완벽한 프라이버시를 보장하는 링크를 생성합니다.

인증

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

기본 URL

모든 API 요청의 기본 URL은 다음과 같습니다.

https://rul.kr

오류 처리

API 요청이 실패할 경우, 표준 HTTP 상태 코드와 함께 오류 메시지를 담은 JSON 객체를 반환합니다. 오류 응답의 형식은 일관되게 유지됩니다.

// 일반적인 오류 응답 형식
{
    "error": "오류에 대한 설명이 여기에 표시됩니다."
}

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

요청 예시

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

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

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

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

3. 비밀 링크 생성

{
    "url": "ENCRYPTED_DATA_HERE",  // `encrypted_data` 필드로 대체됨
    "type": "private",
    "encrypted_data": "U2FsdGVkX1+...encrypted/string",
    "iv": "someInitializationVectorString"
}

응답

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

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

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

지정된 단축 코드에 대한 기본 정보를 조회합니다. 이 엔드포인트는 클릭 수와 같은 상세 통계가 아닌, 링크의 메타데이터를 제공합니다.

요청 예시 (cURL)

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

응답

{
    "short_code": "my-blog-post",
    "type": "public",
    "created_at": "2025-09-12 12:30:00"
}

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

리디렉션

이 경로는 일반적인 API 엔드포인트가 아니며, 사용자를 최종 목적지로 보내는 역할을 합니다. 브라우저에서 단축 URL에 접근할 때 이 경로가 사용됩니다. 동작 방식은 링크의 타입에 따라 달라집니다.

동작 방식

• 공개 링크 (Public Link):

  서버는 302 Found HTTP 상태 코드와 함께 Location 헤더에 원본 URL을 담아 즉시 리디렉션합니다.

• 비밀 링크 (Private Link):

  서버는 바로 리디렉션하지 않습니다. 대신, 암호화된 데이터와 복호화 로직이 포함된 HTML 페이지(loader.html)를 반환합니다. 사용자의 브라우저는 이 페이지의 JavaScript를 실행하여 URL을 복호화한 후, 클라이언트 측에서 최종 목적지로 이동합니다. 이 과정 덕분에 서버는 원본 URL을 전혀 알 수 없습니다.

응답

이 경로의 응답은 JSON이 아닌, HTTP 리디렉션 또는 HTML 페이지입니다.