Introduction

뉴스 큐레이션 서비스, 시점 API 문서입니다.

Overview

이 API는 다음과 같은 기능을 제공합니다:

사용자별 개인화된 이벤트 피드 조회
토픽 관리 및 구독 기능
이벤트 상호작용 (좋아요, 기록)
사용자 프로필 관리
푸시 알림 서비스

Authentication

대부분의 API 엔드포인트는 JWT 토큰을 사용한 Bearer 인증이 필요합니다.

Request headers

Authorization: Bearer <JWT_TOKEN>

Common Response Format

모든 API 응답은 다음과 같은 공통 형태를 가집니다:

{
  "code": 200,
  "message": "요청이 성공적으로 처리되었습니다.",
  "data": { /* 실제 데이터 */ }
}

Resources

Event

이벤트 관련 API입니다.

Get Event Feed

사용자별 개인화된 이벤트 피드를 조회합니다.

$ curl 'http://localhost:8080/api/events/feed?category=%EA%B8%B0%EC%88%A0' -i -X GET

GET /api/events/feed?category=%EA%B8%B0%EC%88%A0 HTTP/1.1
Host: localhost:8080

Parameter Description

Parameter	Description
`category`	피드 카테고리 필터

category

피드 카테고리 필터

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 387

{
  "code" : "200",
  "message" : "성공",
  "data" : [ {
    "id" : 1,
    "topic" : {
      "id" : 1,
      "title" : "AI 기술"
    },
    "title" : "AI 기술의 새로운 혁신",
    "description" : "최신 AI 기술 동향과 발전 방향",
    "imageUrl" : "https://example.com/image1.jpg",
    "eventTime" : [ 2026, 3, 15, 4, 31, 33, 643970139 ],
    "likeCount" : 15
  } ]
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Array`	피드 리스트
`data[].id`	`Number`	피드 ID
`data[].topic`	`Object`	토픽 정보
`data[].topic.id`	`Number`	토픽 ID
`data[].topic.title`	`String`	토픽 제목
`data[].title`	`String`	피드 제목
`data[].description`	`String`	피드 설명
`data[].imageUrl`	`String`	피드 이미지 URL
`data[].eventTime`	`Array`	피드 발생 시간(YYYY-MM-DDTHH:mm:ss)
`data[].likeCount`	`Number`	피드 좋아요 수

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Array

피드 리스트

data[].id

Number

피드 ID

data[].topic

Object

토픽 정보

data[].topic.id

Number

토픽 ID

data[].topic.title

String

토픽 제목

data[].title

String

피드 제목

data[].description

String

피드 설명

data[].imageUrl

String

피드 이미지 URL

data[].eventTime

Array

피드 발생 시간(YYYY-MM-DDTHH:mm:ss)

data[].likeCount

Number

피드 좋아요 수

Toggle Event Like

특정 이벤트에 대한 좋아요를 토글합니다.

$ curl 'http://localhost:8080/api/events/1/like' -i -X POST \
    -H 'Content-Type: application/json'

POST /api/events/1/like HTTP/1.1
Content-Type: application/json
Host: localhost:8080

Table 1. /api/events/{eventId}/like
Parameter	Description
`eventId`	이벤트 ID

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 61

{
  "code" : "200",
  "message" : "성공",
  "data" : null
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Null`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Null

응답 데이터

Topic

토픽 관련 API입니다.

Get All Topics

모든 토픽 목록을 조회합니다.

$ curl 'http://localhost:8080/api/topics?page=0&size=10' -i -X GET

GET /api/topics?page=0&size=10 HTTP/1.1
Host: localhost:8080

Parameter Description

Parameter	Description
`page`	페이지 번호 (0부터 시작, 선택사항)
`size`	페이지 크기 (선택사항)

page

페이지 번호 (0부터 시작, 선택사항)

size

페이지 크기 (선택사항)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 308

{
  "code" : "200",
  "message" : "성공",
  "data" : [ {
    "id" : 1,
    "title" : "인공지능 발전",
    "description" : "AI 기술의 최신 동향과 발전사항"
  }, {
    "id" : 2,
    "title" : "블록체인 기술",
    "description" : "블록체인과 암호화폐의 최신 소식"
  } ]
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Array`	토픽 목록 배열 데이터
`data[].id`	`Number`	토픽 ID
`data[].title`	`String`	토픽 제목
`data[].description`	`String`	토픽 설명

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Array

토픽 목록 배열 데이터

data[].id

Number

토픽 ID

data[].title

String

토픽 제목

data[].description

String

토픽 설명

Get Top K Topics

상위 K개 토픽을 조회합니다.

$ curl 'http://localhost:8080/api/topics/topk?limit=5' -i -X GET

GET /api/topics/topk?limit=5 HTTP/1.1
Host: localhost:8080

Parameter Description

Parameter	Description
`limit`	조회할 상위 토픽 수 (기본값: 5)

limit

조회할 상위 토픽 수 (기본값: 5)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 116

{
  "code" : "200",
  "message" : "성공",
  "data" : [ {
    "id" : 1,
    "title" : "인공지능 발전"
  } ]
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Array`	상위 K개 토픽 배열 데이터
`data[].id`	`Number`	토픽 ID
`data[].title`	`String`	토픽 제목

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Array

상위 K개 토픽 배열 데이터

data[].id

Number

토픽 ID

data[].title

String

토픽 제목

Search Topics

키워드로 토픽을 검색합니다.

$ curl 'http://localhost:8080/api/topics/search?keyword=AI' -i -X GET

GET /api/topics/search?keyword=AI HTTP/1.1
Host: localhost:8080

Parameter Description

Parameter	Description
`keyword`	토픽 제목 또는 설명 검색 키워드

keyword

토픽 제목 또는 설명 검색 키워드

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 182

{
  "code" : "200",
  "message" : "성공",
  "data" : [ {
    "id" : 1,
    "title" : "인공지능 발전",
    "description" : "AI 기술의 최신 동향과 발전사항"
  } ]
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Array`	검색 결과 배열 데이터
`data[].id`	`Number`	토픽 ID
`data[].title`	`String`	토픽 제목
`data[].description`	`String`	토픽 설명

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Array

검색 결과 배열 데이터

data[].id

Number

토픽 ID

data[].title

String

토픽 제목

data[].description

String

토픽 설명

Get Topic Timeline

특정 토픽의 타임라인을 조회합니다.

$ curl 'http://localhost:8080/api/topics/1' -i -X GET

GET /api/topics/1 HTTP/1.1
Host: localhost:8080

Table 2. /api/topics/{topicId}
Parameter	Description
`topicId`	토픽 ID

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 699

{
  "code" : "200",
  "message" : "성공",
  "data" : {
    "id" : 1,
    "title" : "인공지능 발전",
    "description" : "AI 기술의 최신 동향과 발전사항",
    "events" : [ {
      "id" : 1,
      "title" : "ChatGPT 4.0 출시",
      "description" : "OpenAI가 새로운 ChatGPT 버전을 공개했습니다",
      "imageUrl" : "https://example.com/image1.jpg",
      "eventTime" : [ 2024, 12, 4, 10, 0 ],
      "articles" : [ {
        "id" : 201,
        "title" : "ChatGPT 4.0의 새로운 기능들",
        "source" : "OpenAI",
        "url" : "https://example.com/article2"
      } ],
      "likeCount" : 15,
      "isActive" : true
    } ],
    "isFollowing" : true
  }
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Object`	토픽 타임라인 데이터
`data.id`	`Number`	토픽 ID
`data.title`	`String`	토픽 제목
`data.description`	`String`	토픽 설명
`data.isFollowing`	`Boolean`	사용자의 토픽 팔로우 여부
`data.events`	`Array`	타임라인 이벤트 목록
`data.events[].id`	`Number`	이벤트 ID
`data.events[].title`	`String`	이벤트 제목
`data.events[].description`	`String`	이벤트 설명
`data.events[].imageUrl`	`String`	이벤트 이미지 URL
`data.events[].eventTime`	`Array`	이벤트 발생 시간
`data.events[].likeCount`	`Number`	이벤트 좋아요 수
`data.events[].isActive`	`Boolean`	이벤트 활성/좋아요 여부
`data.events[].articles`	`Array`	이벤트 관련 기사 목록
`data.events[].articles[].id`	`Number`	기사 ID
`data.events[].articles[].title`	`String`	기사 제목
`data.events[].articles[].source`	`String`	기사 출처
`data.events[].articles[].url`	`String`	기사 URL

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Object

토픽 타임라인 데이터

data.id

Number

토픽 ID

data.title

String

토픽 제목

data.description

String

토픽 설명

data.isFollowing

Boolean

사용자의 토픽 팔로우 여부

data.events

Array

타임라인 이벤트 목록

data.events[].id

Number

이벤트 ID

data.events[].title

String

이벤트 제목

data.events[].description

String

이벤트 설명

data.events[].imageUrl

String

이벤트 이미지 URL

data.events[].eventTime

Array

이벤트 발생 시간

data.events[].likeCount

Number

이벤트 좋아요 수

data.events[].isActive

Boolean

이벤트 활성/좋아요 여부

data.events[].articles

Array

이벤트 관련 기사 목록

data.events[].articles[].id

Number

기사 ID

data.events[].articles[].title

String

기사 제목

data.events[].articles[].source

String

기사 출처

data.events[].articles[].url

String

기사 URL

Toggle Topic Subscription

특정 토픽에 대한 구독을 토글합니다.

$ curl 'http://localhost:8080/api/topics/1/toggle-subscription' -i -X POST \
    -H 'Content-Type: application/json'

POST /api/topics/1/toggle-subscription HTTP/1.1
Content-Type: application/json
Host: localhost:8080

Table 3. /api/topics/{topicId}/toggle-subscription
Parameter	Description
`topicId`	토픽 ID

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 61

{
  "code" : "200",
  "message" : "성공",
  "data" : null
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Null`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Null

응답 데이터

Interaction

사용자 상호작용 관련 API입니다.

Record Interaction

사용자의 이벤트 상호작용을 기록합니다.

$ curl 'http://localhost:8080/api/interactions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{
  "eventId" : 1,
  "interactionType" : "VIEWED"
}'

POST /api/interactions HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Length: 51
Host: localhost:8080

{
  "eventId" : 1,
  "interactionType" : "VIEWED"
}

Path Type Description

Path	Type	Description
`eventId`	`Number`	사용자가 상호작용한 이벤트 ID
`interactionType`	`String`	상호작용 유형 (VIEWED, ARTICLE_CLICKED, TOPIC_VIEWED, TOPIC_FOLLOWED, TOPIC_UNFOLLOWED)

eventId

Number

사용자가 상호작용한 이벤트 ID

interactionType

String

상호작용 유형 (VIEWED, ARTICLE_CLICKED, TOPIC_VIEWED, TOPIC_FOLLOWED, TOPIC_UNFOLLOWED)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 61

{
  "code" : "200",
  "message" : "성공",
  "data" : null
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Null`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Null

응답 데이터

User

사용자 관련 API입니다.

Get Current User

현재 사용자 정보를 조회합니다.

$ curl 'http://localhost:8080/api/users/me' -i -X GET \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

GET /api/users/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Host: localhost:8080

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 181

{
  "code" : "200",
  "message" : "성공",
  "data" : {
    "id" : 1,
    "name" : "Test User",
    "email" : "test@example.com",
    "profileUrl" : null,
    "role" : "USER"
  }
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Object`	Current user data
`data.id`	`Number`	사용자 ID
`data.name`	`String`	사용자 이름
`data.email`	`String`	사용자 이메일
`data.profileUrl`	`Null`	사용자 프로필 이미지 URL
`data.role`	`String`	사용자 역할 (USER, ADMIN)

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Object

Current user data

data.id

Number

사용자 ID

data.name

String

사용자 이름

data.email

String

사용자 이메일

data.profileUrl

Null

사용자 프로필 이미지 URL

data.role

String

사용자 역할 (USER, ADMIN)

Update Device Token

사용자의 디바이스 토큰을 업데이트합니다.

$ curl 'http://localhost:8080/api/users/device-token' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{
  "deviceToken" : "fcm_device_token_12345"
}'

POST /api/users/device-token HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Length: 46
Host: localhost:8080

{
  "deviceToken" : "fcm_device_token_12345"
}

Path Type Description

Path	Type	Description
`deviceToken`	`String`	푸시 알림용 FCM 디바이스 토큰

deviceToken

String

푸시 알림용 FCM 디바이스 토큰

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 61

{
  "code" : "200",
  "message" : "성공",
  "data" : null
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Null`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Null

응답 데이터

Withdraw User

사용자 탈퇴를 처리합니다.

$ curl 'http://localhost:8080/api/users/withdraw' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -d '{
  "reason" : "서비스 불만족",
  "feedback" : "앱 속도가 너무 느림"
}'

POST /api/users/withdraw HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Length: 84
Host: localhost:8080

{
  "reason" : "서비스 불만족",
  "feedback" : "앱 속도가 너무 느림"
}

Path Type Description

Path	Type	Description
`reason`	`String`	탈퇴 사유
`feedback`	`String`	추가 피드백

reason

String

탈퇴 사유

feedback

String

추가 피드백

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 61

{
  "code" : "200",
  "message" : "성공",
  "data" : null
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Null`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Null

응답 데이터

Push Notification

푸시 알림 관련 API입니다.

Send Push Message by Topic

토픽 기반으로 푸시 메시지를 전송합니다.

$ curl 'http://localhost:8080/api/notifications/push?by=topic' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "topicId" : 1
}'

POST /api/notifications/push?by=topic HTTP/1.1
Content-Type: application/json
Content-Length: 19
Host: localhost:8080

{
  "topicId" : 1
}

Parameter Description

Parameter	Description
`by`	Push 종류

by

Push 종류

Path Type Description

Path	Type	Description
`topicId`	`Number`	토픽 ID

topicId

Number

토픽 ID

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 60

{
  "code" : "200",
  "message" : "성공",
  "data" : { }
}

Path Type Description

Path	Type	Description
`code`	`String`	응답 코드 (200, 400, 500 등)
`message`	`String`	응답 메시지
`data`	`Object`	응답 데이터

code

String

응답 코드 (200, 400, 500 등)

message

String

응답 메시지

data

Object

응답 데이터

OpenAPI 3.0 Specification

이 API의 OpenAPI 3.0 스펙을 다운로드할 수 있습니다:

📄 OpenAPI YAML 다운로드

Appendix

HTTP Status Codes

시점 API는 다음과 같은 HTTP 상태 코드를 사용합니다:

Status code Usage

Status code	Usage
`200 OK`	요청이 성공적으로 처리됨
`400 Bad Request`	잘못된 요청 (요청 형식 오류, 필수 파라미터 누락 등)
`401 Unauthorized`	인증이 필요하거나 인증 정보가 유효하지 않음
`404 Not Found`	요청한 리소스를 찾을 수 없음
`500 Internal Server Error`	서버 내부 오류

200 OK

요청이 성공적으로 처리됨

400 Bad Request

잘못된 요청 (요청 형식 오류, 필수 파라미터 누락 등)

401 Unauthorized

인증이 필요하거나 인증 정보가 유효하지 않음

404 Not Found

요청한 리소스를 찾을 수 없음

500 Internal Server Error

서버 내부 오류