📚 블로그 API 문서

마크다운 기반 블로그 시스템의 REST API 문서입니다. Python docs 스타일로 작성되었습니다.

Base URL: http://www.closetoya.com/api/v1

🔐 인증

이 API는 OAuth 2.0을 사용하여 인증합니다. 쓰기 작업을 위해서는 유효한 액세스 토큰이 필요합니다.

POST
/auth/login
OAuth 클라이언트 자격 증명을 사용하여 로그인하고 액세스 토큰을 받습니다.

요청 파라미터

파라미터타입필수설명
emailstring✓사용자 이메일
passwordstring✓사용자 비밀번호
client_idstring✓OAuth 클라이언트 ID
client_secretstring✓OAuth 클라이언트 시크릿
grant_typestring✓grant_type (password)

요청 예시

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" }'

📖 포스트 읽기 (공개)

인증 없이 포스트를 읽을 수 있습니다.

GET
/posts
공개된 포스트 목록을 페이지네이션과 함께 조회합니다.

쿼리 파라미터

파라미터타입기본값설명
per_pageinteger20페이지당 포스트 수
GET
/posts/{slug}
특정 슬러그의 포스트를 조회합니다.
GET
/posts/{slug}/content
포스트의 마크다운 내용만 조회합니다.

✍️ 포스트 쓰기 (인증 필요)

⚠️ 인증 필요: 이 엔드포인트들은 유효한 OAuth 액세스 토큰이 필요합니다.
POST
/posts
새로운 포스트를 생성합니다.

요청 파라미터

파라미터타입필수설명
titlestring✓포스트 제목
contentstring✓마크다운 내용
slugstringURL 슬러그 (자동 생성)
excerptstring요약
category_pathstring카테고리 경로
parent_slugstring부모 포스트 슬러그
is_publishedboolean발행 여부 (기본: true)

요청 예시

curl -X POST "http://www.closetoya.com/api/v1/posts" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "새로운 포스트", "content": "# 제목\n\n내용입니다.", "category_path": "기술/프로그래밍", "is_published": true }'
PUT
/posts/{id}
기존 포스트를 수정합니다.
DELETE
/posts/{id}
포스트를 삭제합니다.

🔍 검색

인증 없이 검색 기능을 사용할 수 있습니다.

GET
/search
포스트를 검색합니다.

쿼리 파라미터

파라미터타입필수설명
qstring✓검색어
categorystring카테고리 필터
authorstring작성자 필터
sortstring정렬 (relevance, date, views)
per_pageinteger페이지당 결과 수
GET
/search/suggestions
검색어 제안을 제공합니다.

🎲 기타

GET
/random
랜덤 포스트를 조회합니다.

📋 응답 형식

모든 API 응답은 JSON 형식으로 반환됩니다.

성공 응답

{ "posts": [...], "pagination": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 100 } }

에러 응답

{ "error": "error_code", "message": "에러 메시지", "errors": { "field": ["검증 에러"] } }

🔗 추가 리소스