Skip to content

Shortlink API Spec

wcorn edited this page Aug 22, 2026 · 5 revisions

API 설계: 단축 URL (링크)

확정 명세 · 유스케이스 · 아키텍처 · 데이터 모델

두 종류의 표면이 있다. 관리 API는 /api/shortlinks + JWT 인증 + orino 공통 envelope { code, data }. 공개 리다이렉트는 /r/** + 인증 없음 + envelope 없음 + HTML/302. 섞지 않는다.

1. 엔드포인트 요약

1.1 관리 API (인증 필요 · orino.dev)

그룹 메서드 경로 설명
요약 GET /api/shortlinks/summary /select 카드 메타
목록 GET /api/shortlinks 검색·상태·태그 필터
발급 POST /api/shortlinks 링크 생성
상세 GET /api/shortlinks/{slug} 단건(이력 포함)
수정 PATCH /api/shortlinks/{slug} 목적지·메모·태그·만료·비밀번호
상태 POST /api/shortlinks/{slug}/toggle 활성 ↔ 비활성
즐겨찾기 POST /api/shortlinks/{slug}/favorite 토글
삭제 DELETE /api/shortlinks/{slug} 소프트 삭제
통계 GET /api/shortlinks/{slug}/stats 방문·유입·기기·국가
슬러그 GET /api/shortlinks/slug-available 커스텀 슬러그 중복 검사
태그 GET /api/shortlinks/tags 사이드바 태그 + 개수
프리뷰 GET /api/shortlinks/og-preview 목적지 OG 조회(비동기 · 실패 허용)

경로 키는 id가 아니라 slug다. 슬러그는 불변이고(명세 §5.2) 사용자가 실제로 보는 식별자다. FE 라우트도 /links/{slug}로 맞춘다(결정 기록 D-5).

1.2 공개 리다이렉트 (인증 없음 · s.orino.dev)

메서드 공개 주소 내부 경로 응답
GET s.orino.dev/{slug} /r/{slug} 302 · 404 HTML · 200 비밀번호 화면
POST s.orino.dev/{slug} /r/{slug}/unlock 302 · 200 재입력 화면
GET s.orino.dev/robots.txt — 게이트웨이 directResponse (BE 미도달)

2. 관리 API

GET /api/shortlinks/summary

/select 링크 카드의 메타 줄. 실패하면 FE는 메타 줄 자체를 그리지 않는다(화면 §2).

// Response.data
{ "total": 34, "visitsThisWeek": 128 }

GET /api/shortlinks

?query=  슬러그·목적지·메모 부분 일치
&status= ALL | ACTIVE | INACTIVE     // INACTIVE = 꺼짐 + 만료 (화면 칩과 1:1)
&tag=    태그명
// Response.data
{
  "counts": { "all": 34, "active": 29, "inactive": 5 },   // 상태 칩 숫자
  "favorites": [ /* LinkSummary[] */ ],                    // 즐겨찾기 섹션
  "recent":    [ /* LinkSummary[] */ ]                     // 최근 발급 섹션
}

// LinkSummary
{
  "slug": "9dwqr",
  "shortUrl": "https://s.orino.dev/9dwqr",   // 서버가 조립해 내려준다(FE에 도메인 하드코딩 금지)
  "targetUrl": "https://files.example.com/...",
  "memo": "부모님께 보낸 8월 흐름",
  "tags": ["가족"],
  "custom": false,                            // 커스텀 슬러그 배지
  "favorite": false,
  "state": "ACTIVE",                          // ACTIVE | DISABLED | EXPIRED  ← 파생값
  "hasPassword": false,
  "visitCount": 76,                           // 사람 방문만
  "lastVisitedAt": "2026-08-20T11:02:00Z"     // null 가능
}

state는 저장값이 아니라 status + expires_at 조합의 파생이다(데이터 모델 §3). 화면은 이 값 하나만 보고 배지를 정한다.

POST /api/shortlinks

// Request
{
  "targetUrl": "https://files.example.com/...",   // 필수
  "slug": "jeju",         // 선택. 비우면 자동 5자
  "memo": "제주 보드",     // 선택
  "tags": ["여행"],        // 선택
  "expiresAt": "2026-12-31T23:59:59+09:00",  // 선택
  "password": "····"      // 선택. 있으면 BCrypt로 저장
}
// Response.data = LinkSummary + { "qrPayload": "https://s.orino.dev/jeju" }
실패 코드 상태
스킴 불허(javascript: 등) SL-ERR-001 400
목적지가 s.orino.dev (루프) SL-ERR-002 400
커스텀 슬러그 중복 SL-ERR-003 409
슬러그 문자셋 위반 SL-ERR-004 400
자동 슬러그 생성 5회 실패 SL-ERR-005 500

중복(SL-ERR-003)은 삭제된 링크의 슬러그에도 발생한다. 그게 영구 점유다(명세 §3.1). 메시지는 이미 사용 중이에요 하나로, 삭제된 것인지 살아 있는 것인지 구분해 알려주지 않는다.

GET /api/shortlinks/{slug}

// Response.data = LinkSummary + {
  "createdAt": "2026-08-03T09:12:00Z",
  "expiresAt": null,
  "og": { "title": "…", "imageUrl": "…" },   // null 가능
  "targetHistory": [
    { "targetUrl": "https://…/aug.jpg", "reason": "서명 만료로 재발급", "changedAt": "2026-08-14T…" },
    { "targetUrl": "https://…/old.jpg", "reason": "최초 발급",         "changedAt": "2026-08-03T…" }
  ]
}

PATCH /api/shortlinks/{slug}

보낸 필드만 바꾼다. slug는 받지 않는다(명세 §5.2).

{
  "targetUrl": "https://…",          // 바뀌면 이력 1줄 추가
  "targetChangeReason": "서명 만료로 재발급",  // targetUrl 있을 때만 의미
  "memo": "…", "tags": ["가족"],
  "expiresAt": null,                 // null 명시 = 만료 해제
  "password": null                   // null 명시 = 비밀번호 해제 / 문자열 = 재설정
}

목적지 교체를 별도 엔드포인트로 나누지 않는다. 나누면 "메모만 고치다가 목적지도 같이 고치는" 흔한 경우에 요청이 둘로 갈린다. 대신 targetUrl이 실제로 바뀐 경우에만 이력을 쓴다(같은 값 재전송은 이력 없음).

POST /api/shortlinks/{slug}/toggle · /favorite · DELETE /api/shortlinks/{slug}

// toggle Response.data → { "state": "DISABLED" }
// favorite Response.data → { "favorite": true }
// DELETE  → 소프트 삭제. 204. 슬러그는 이후 영구 점유

GET /api/shortlinks/{slug}/stats?range=30d

// Response.data
{
  "totalVisits": 142,          // 사람만
  "botVisits": 18,             // 따로 (SL-017)
  "last7Days": 23,
  "lastVisitedAt": "2026-08-20T11:02:00Z",
  "daily": [ { "date": "2026-07-25", "count": 0 }, … ],   // 요청 범위 전체, 빈 날 0으로 채워서
  "referrers": [ { "domain": "kakaotalk", "count": 88 }, … ],   // 도메인까지만
  "devices":   [ { "device": "MOBILE", "ratio": 0.78 }, … ],
  "countries": [ { "country": "KR", "ratio": 0.92 }, … ]
}

daily는 집계 테이블에서 오므로 범위 제한이 없다. referrers·devices·countries는 원시에서만 나오므로 90일 창을 넘어가면 비어 간다(명세 §8.3). 화면 기본이 30일이라 평소엔 보이지 않는 경계다.

GET /api/shortlinks/slug-available?slug=jeju

{ "available": false }

FE는 디바운스해서 부른다. 사용 중이면 FieldError — 이미 사용 중이에요.

GET /api/shortlinks/tags

[ { "name": "가족", "count": 9 }, { "name": "여행", "count": 7 } ]

GET /api/shortlinks/og-preview?url=…

// 성공
{ "ok": true, "title": "2026 여름 가족사진.zip — Google Drive", "imageUrl": "https://…" }
// 실패 — 이유를 나누지 않는다 (아키텍처 §5)
{ "ok": false }

이 엔드포인트는 발급 흐름을 막지 않는다. 느리거나 죽어도 POST /api/shortlinks는 정상 동작한다.


3. 공개 리다이렉트

GET /r/{slug} (공개 주소 s.orino.dev/{slug})

조건 응답
활성 · 미만료 · 비밀번호 없음 302 + Location + Cache-Control: no-store + Referrer-Policy: no-referrer
활성 · 비밀번호 있음 200 비밀번호 확인 화면(HTML)
없음 · 꺼짐 · 만료 · 삭제 404 + 실패 화면(HTML) — 넷을 구분하지 않는다

Location 조립은 명세 §6.4를 따른다.

방문 쿼리 없음                    → 목적지 그대로 ( ? 를 붙이지 않는다 )
방문 쿼리 있음                    → 목적지 뒤에 ? 또는 & 로 이어붙임
목적지에 서명 파라미터가 있음      → 방문 쿼리를 버린다
   (X-Amz-Signature · X-Goog-Signature · Signature)

POST /r/{slug}/unlock

application/x-www-form-urlencoded, 필드 password. 확인 화면의 form이 직접 보낸다(JS·JSON 아님 — 서버 렌더 화면이므로).

결과 응답
통과 302 (위와 동일 헤더). 쿠키·세션을 만들지 않는다 — 다음 방문에 다시 입력
실패 200 확인 화면 재표시. 비밀번호가 맞지 않아요 한 줄
슬러그당 분당 10회 초과 429. 화면은 동일, 문구만 잠시 후 다시 시도해 주세요

실패 화면에서 "이 링크에는 비밀번호가 없다"와 "비밀번호가 틀렸다"를 구분하지 않는다. 비밀번호 없는 슬러그에 POST가 오면 GET과 같은 판정으로 떨어진다.

4. 에러 코드

ErrorCode enum에 추가한다(기존 GLB · AUTH · SP · PLN 옆에 SL).

코드 메시지 상태
SL-ERR-001 지원하지 않는 주소 형식입니다. 400
SL-ERR-002 목적지가 단축 주소일 수 없습니다. 400
SL-ERR-003 이미 사용 중인 주소입니다. 409
SL-ERR-004 사용할 수 없는 문자가 있습니다. 400
SL-ERR-005 주소를 만들지 못했습니다. 다시 시도해 주세요. 500
SL-ERR-006 존재하지 않는 링크입니다. 404

SL-ERR-006은 관리 API 전용이다. 공개 리다이렉트는 envelope를 쓰지 않고 HTML 404 한 장으로만 답한다 — 에러 코드를 내보내는 순간 그것 자체가 정보다(명세 §7).

5. 테스트로 고정할 계약

  1. /r/**만 인증 없이 열린다. /api/shortlinks/**는 토큰 없으면 401
  2. 없음 · 꺼짐 · 만료 · 삭제 네 경우의 응답이 바이트 단위로 같다(상태·본문·헤더)
  3. 302 응답에 Cache-Control: no-store가 있다
  4. 목적지에 서명 파라미터가 있으면 방문 쿼리가 전달되지 않는다
  5. 삭제한 링크의 슬러그로 재발급하면 SL-ERR-003
  6. 대문자 슬러그로 방문해도 같은 링크로 리다이렉트된다
  7. 방문 기록 저장이 실패해도 302가 나간다
  8. OG 프리뷰가 사설 IP로 해석되는 호스트를 거부하고, 그 이유를 응답에 담지 않는다

Clone this wiki locally