Repository navigation
Shortlink API Spec
두 종류의 표면이 있다. 관리 API는
/api/shortlinks+ JWT 인증 + orino 공통 envelope{ code, data }. 공개 리다이렉트는/r/**+ 인증 없음 + envelope 없음 + HTML/302. 섞지 않는다.
| 그룹 | 메서드 | 경로 | 설명 |
|---|---|---|---|
| 요약 | GET | /api/shortlinks/summary |
/select 카드 메타 |
| 목록 | GET | /api/shortlinks |
검색·상태·태그 필터 |
| 발급 | POST | /api/shortlinks |
링크 생성 |
| 상세 | GET | /api/shortlinks/{slug} |
단건(이력 포함) |
| 수정 | PATCH | /api/shortlinks/{slug} |
목적지·제목·설명(memo)·태그·만료·비밀번호 |
| 상태 | 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).
| 메서드 | 공개 주소 | 내부 경로 | 응답 |
|---|---|---|---|
| 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 미도달) |
/select 링크 카드의 메타 줄. 실패하면 FE는 메타 줄 자체를 그리지 않는다(화면 §2).
?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/...",
"title": "8월 가족사진", // null 가능. 화면은 null이면 짧은 주소를 제목 자리에 둔다
"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). 화면은 이 값 하나만 보고 배지를 정한다.
구현 시점 보강(#1236)
recent에 즐겨찾기는 들어가지 않는다. 두 섹션에 같은 카드가 두 번 나오면counts.all과 눈에 보이는 행 수가 어긋난다counts는 상태 필터를 적용하기 전의 검색·태그 결과를 기준으로 센다. 걸러진 뒤에 세면 지금 눌린 칩 말고는 숫자를 알 수 없다visitCount는 0,lastVisitedAt은null로 고정이다 — 방문 기록이 #1240에서 붙는다. 필드를 미리 내려 FE 계약을 고정하고 값만 나중에 채운다(summary.visitsThisWeek도 같다)
// Request
{
"targetUrl": "https://files.example.com/...", // 필수
"slug": "jeju", // 선택. 비우면 자동 5자
"title": "제주 보드", // 선택. 100자 이내, 공백만이면 null
"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). 메시지는이미 사용 중이에요하나로, 삭제된 것인지 살아 있는 것인지 구분해 알려주지 않는다.
// 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…" }
]
}보낸 필드만 바꾼다. slug는 받지 않는다(명세 §5.2).
{
"targetUrl": "https://…", // 바뀌면 이력 1줄 추가
"targetChangeReason": "서명 만료로 재발급", // targetUrl 있을 때만 의미
"title": "…", // 빈 문자열 = 제목 지우기 / 생략 = 변경 없음
"memo": "…", "tags": ["가족"],
"expiresAt": null, // null 명시 = 만료 해제
"password": null // null 명시 = 비밀번호 해제 / 문자열 = 재설정
}목적지 교체를 별도 엔드포인트로 나누지 않는다. 나누면 "메모만 고치다가 목적지도 같이 고치는" 흔한 경우에 요청이 둘로 갈린다. 대신
targetUrl이 실제로 바뀐 경우에만 이력을 쓴다(같은 값 재전송은 이력 없음).
// toggle Response.data → { "state": "DISABLED" }
// favorite Response.data → { "favorite": true }
// DELETE → 소프트 삭제. 슬러그는 이후 영구 점유구현 시점 정정(#1236): DELETE는
204**200 + 공통 envelope({ code, data: null })**다. orino의 모든 DELETE가 그 형태이고, FE 인터셉터도 envelope를 전제로 짜여 있다 — 이 엔드포인트 하나만 204로 두면 링크 화면에서만 응답 처리가 갈린다.
// 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일이라 평소엔 보이지 않는 경계다.
구현 시점 보강(#1240)
range는7d·30d형식이고 잘못된 값에 에러를 내지 않는다 — 30일로 본다. 통계는 참고치이고, 범위 하나 때문에 화면이 비는 것보다 기본값으로 보여 주는 편이 낫다. 상한은 365일lastVisitedAt도 원시에서 나온다. 90일 넘게 방문이 없으면 원시가 지워져null이 된다 — 총 방문(totalVisits)은 집계에서 나오므로 그대로 남는다. "방문 수는 있는데 마지막 방문이 비어 있는" 조합이 정상이다devices의 비율 분모에서UNKNOWN을 빼지 않는다. 판정 실패를 없는 것처럼 만들면 합이 100%가 되면서 정확해 보이는 착시가 생긴다. 그래서 비율의 합이 1이 아닐 수 있다countries는 항상 빈 배열이다 — 국가를 판정하지 않기로 했다(2026-08-24, D-9 뒤집힘 · #1241 미착수 종료). 화면은 그 줄을 그리지 않는다
{ "available": false }FE는 디바운스해서 부른다. 사용 중이면 FieldError — 이미 사용 중이에요.
구현 시점 보강(#1236): 문자셋·길이를 벗어난 슬러그에는
available: false가 아니라SL-ERR-004(400) 로 답한다. 둘을 같은 응답으로 뭉개면 화면이이미 사용 중이에요를 띄우는데, 실제로는 아무도 안 쓰는 주소이고 사용자는 다른 이름을 계속 찾게 된다.
[ { "name": "가족", "count": 9 }, { "name": "여행", "count": 7 } ]// 성공
{ "ok": true, "title": "2026 여름 가족사진.zip — Google Drive", "imageUrl": "https://…" }
// 실패 — 이유를 나누지 않는다 (아키텍처 §5)
{ "ok": false }이 엔드포인트는 발급 흐름을 막지 않는다. 느리거나 죽어도 POST /api/shortlinks는 정상 동작한다.
| 조건 | 응답 |
|---|---|
| 활성 · 미만료 · 비밀번호 없음 |
302 + Location + Cache-Control: no-store + Referrer-Policy: no-referrer
|
| 활성 · 비밀번호 있음 | 200 비밀번호 확인 화면(HTML) |
| 없음 · 꺼짐 · 만료 · 삭제 | 404 + 실패 화면(HTML) — 넷을 구분하지 않는다 |
Location 조립은 명세 §6.4를 따른다.
방문 쿼리 없음 → 목적지 그대로 ( ? 를 붙이지 않는다 )
방문 쿼리 있음 → 목적지 뒤에 ? 또는 & 로 이어붙임
목적지에 서명 파라미터가 있음 → 방문 쿼리를 버린다
(X-Amz-Signature · X-Goog-Signature · Signature)
application/x-www-form-urlencoded, 필드 password. 확인 화면의 form이 직접 보낸다(JS·JSON 아님 — 서버 렌더 화면이므로).
| 결과 | 응답 |
|---|---|
| 통과 | 302 (위와 동일 헤더). 쿠키·세션을 만들지 않는다 — 다음 방문에 다시 입력 |
| 실패 | 200 확인 화면 재표시. 비밀번호가 맞지 않아요 한 줄 |
| 슬러그당 분당 10회 초과 | 429. 화면은 동일, 문구만 잠시 후 다시 시도해 주세요
|
실패 화면에서 "이 링크에는 비밀번호가 없다"와 "비밀번호가 틀렸다"를 구분하지 않는다. 비밀번호 없는 슬러그에 POST가 오면 GET과 같은 판정으로 떨어진다.
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).
-
/r/**만 인증 없이 열린다./api/shortlinks/**는 토큰 없으면 401 - 없음 · 꺼짐 · 만료 · 삭제 네 경우의 응답이 바이트 단위로 같다(상태·본문·헤더)
- 302 응답에
Cache-Control: no-store가 있다 - 목적지에 서명 파라미터가 있으면 방문 쿼리가 전달되지 않는다
- 삭제한 링크의 슬러그로 재발급하면
SL-ERR-003 - 대문자 슬러그로 방문해도 같은 링크로 리다이렉트된다
- 방문 기록 저장이 실패해도 302가 나간다
- OG 프리뷰가 사설 IP로 해석되는 호스트를 거부하고, 그 이유를 응답에 담지 않는다