API 문서 - 숏.한국

소개

숏.한국 API는 URL 단축 서비스를 프로그래밍 방식으로 사용할 수 있게 해주는 RESTful API입니다. 이 API를 통해 다음과 같은 기능을 사용할 수 있습니다:

URL 단축
커스텀 단축 코드 지정
만료 기간 설정

API는 JSON 형식으로 요청과 응답을 처리합니다.

인증

현재 API는 인증 없이 사용할 수 있습니다. 향후 버전에서는 API 키 인증이 추가될 예정입니다.

엔드포인트

URL 단축

POST https://숏.한국/api.php

URL을 단축하고 커스텀 코드를 지정합니다.

API 정보

GET https://숏.한국/api.php

API 정보와 사용 가능한 엔드포인트 목록을 반환합니다.

파라미터

URL 단축 (POST)

파라미터	타입	필수	설명
original_url	string	✓	단축할 원본 URL
custom_code	string	✗	사용자 지정 단축 코드 (한글, 영문, 숫자, 밑줄(_), 하이픈(-) 사용 가능, 미입력 시 자동 생성)
expire_duration	string	✗	만료 기간 (24h, 48h, 1week, 1month 중 하나만 선택 가능, 기본값: 1week)

만료 기간 설정

만료 기간은 다음 네 가지 옵션 중 하나만 선택할 수 있습니다:

24h - 24시간
48h - 48시간
1week - 1주일 (기본값)
1month - 1개월

다른 값을 지정하거나 날짜를 직접 입력할 수 없습니다. 위 옵션 중 하나만 사용 가능합니다.

응답

응답 형식

{
    "status": "success|error",
    "message": "응답 메시지",
    "data": {
        "short_url": "단축된 URL",
        "original_url": "원본 URL",
        "code": "단축 코드",
        "expiration_date": "만료 일자"
    }
}

성공 응답 예시

{
    "status": "success",
    "message": "URL이 성공적으로 단축되었습니다.",
    "data": {
        "short_url": "https://숏.한국/자료",
        "original_url": "https://example.com/very-long-url",
        "code": "자료",
        "expiration_date": "2024-03-20 15:30:00"
    }
}

예제

cURL

curl -X POST https://숏.한국/api.php \
    -H "Content-Type: application/json" \
    -d '{
        "original_url": "https://example.com/very-long-url",
        "custom_code": "자료",  // 선택사항, 입력하지 않으면 자동 생성됨
        "expire_duration": "1week"
    }'

JavaScript (Fetch API)

fetch('https://숏.한국/api.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        original_url: 'https://example.com/very-long-url',
        custom_code: '자료',
        expire_duration: '1week'
    })
})
.then(response => response.json())
.then(data => console.log(data));

Python (Requests)

import requests
import json

url = 'https://숏.한국/api.php'
data = {
    'original_url': 'https://example.com/very-long-url',
    'custom_code': '자료',
    'expire_duration': '1week'
}

response = requests.post(url, json=data)
print(response.json())

에러

상태 코드	설명
400	잘못된 요청 (필수 파라미터 누락, 잘못된 형식 등)
401	인증 실패 (향후 API 키 인증 시)
404	리소스를 찾을 수 없음
405	허용되지 않는 메소드
409	단축 코드 충돌 (이미 사용 중인 코드)
500	서버 내부 오류

에러 응답 예시

{
    "status": "error",
    "message": "이미 사용 중인 단축 코드입니다. 2024-03-20 이후에 사용 가능합니다."
}

숏.한국 API 문서

목차

소개

인증