API v1 Documentation

핵심 규칙

• 권장 인증 흐름은 POST /login 으로 Bearer 토큰 발급, GET /token/validate 로 상태 확인, POST /token/reissue 로 새 토큰 재발급입니다.
• 장기 운영용 외부 연동은 POST /tokens 로 별도 API 토큰을 발급해서 사용하는 방식을 권장합니다.
• 공개 카테고리/검색 API는 status = published 이고 is_hidden = false 인 글만 반환합니다.
• GET /posts, GET /posts/{slug}, GET /random 은 현재 구현상 is_hidden = false 만 확인합니다.
• 포스트 생성 시 문서용 excerpt, is_published 는 사용되지 않습니다. 상태 전환은 수정 API의 status 필드로 처리합니다.
• 포스트 수정은 /posts/{id} 와 /posts/slug/{slug} 두 방식이 모두 제공됩니다.

권장 인증 흐름

curl -X POST "http://www.closetoya.com/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

curl -X POST "http://www.closetoya.com/api/v1/tokens" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token_name": "external-writer-prod"
  }'

curl -X POST "http://www.closetoya.com/api/v1/posts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "외부 API로 쓴 글",
    "content": "# 제목

본문",
    "category_path": "api/external"
  }'

고급 OAuth 흐름

curl -X POST "http://www.closetoya.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "password"
  }'

공개 포스트 조회

포스트 쓰기

curl -X PUT "http://www.closetoya.com/api/v1/posts/123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "수정된 제목",
    "content": "# 수정된 본문

내용을 바꿉니다.",
    "category_path": "dev/api",
    "status": "published"
  }'

curl -X PUT "http://www.closetoya.com/api/v1/posts/slug/existing-post-slug" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "draft"
  }'

curl -X DELETE "http://www.closetoya.com/api/v1/posts/123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

curl -X POST "http://www.closetoya.com/api/v1/posts/123/unhide" \
  -H "Authorization: Bearer ACCESS_TOKEN"

카테고리와 검색

첨부파일과 고급 OAuth

응답 형식 예시

{
  "message": "포스트가 생성되었습니다.",
  "post": {
    "id": 12,
    "title": "새 글",
    "slug": "새-글",
    "category_path": "tech/api",
    "parent_id": null,
    "created_at": "2026-03-13T01:23:45.000000Z"
  }
}

{
  "error": "validation_error",
  "message": "입력 데이터가 올바르지 않습니다.",
  "errors": {
    "title": [
      "The title field is required."
    ]
  }
}