← 홈으로 돌아가기

API 명세서 및 Swagger 사용 가이드

목차

  1. API 기본 정보
  2. Swagger UI 사용법
  3. 인증 방법
  4. 주요 API 엔드포인트
  5. iOS 앱 개발자를 위한 가이드

API 기본 정보

Base URL

https://rankly.kr/api/v1

API 버전

인증 방식

Swagger UI 사용법

1. Swagger UI 접속

브라우저에서 다음 URL로 접속:

https://rankly.kr/api/v1/docs

2. 인증 토큰 설정

  1. Swagger UI 상단의 "Authorize" 버튼 클릭
  2. Bearer {token} 형식으로 토큰 입력
  3. 예: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
  4. "Authorize" 버튼 클릭하여 저장
  5. "Close" 버튼으로 모달 닫기

3. API 테스트 방법

  1. 원하는 엔드포인트 섹션 확장
  2. "Try it out" 버튼 클릭
  3. 필요한 파라미터 입력
  4. "Execute" 버튼 클릭
  5. 응답 결과 확인

4. OpenAPI JSON 다운로드

다음 URL에서 OpenAPI 스펙을 JSON 형식으로 다운로드 가능:

https://rankly.kr/api/v1/openapi.json

이 파일을 사용하여: - Postman, Insomnia 등 API 클라이언트에 import - 코드 생성 도구 사용 (예: Swagger Codegen) - API 문서 자동 생성

인증 방법

1. 로그인하여 토큰 획득

엔드포인트: POST /api/v1/accounts/login/

요청 예시:

{
  "email": "user@example.com",
  "password": "password123"
}

응답 예시:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

2. API 요청 시 토큰 사용

모든 인증이 필요한 API 요청 시 Authorization 헤더에 토큰 포함:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

3. 토큰 갱신

엔드포인트: POST /api/v1/accounts/token/refresh/

요청 예시:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

주요 API 엔드포인트

계정 (Accounts)

OTP 발송

요청 예시:

{
  "email": "user@example.com"
}

OTP 검증

요청 예시:

{
  "email": "user@example.com",
  "otp": "123456"
}

회원가입

요청 예시:

{
  "email": "user@example.com",
  "otp": "123456",
  "name": "홍길동",
  "password": "SecurePass123!",
  "confirm_password": "SecurePass123!",
  "nickname": "귀여운토끼123",
  "referral_code": "ABC123"
}

응답 예시:

{
  "detail": "회원가입이 완료되었습니다.",
  "user_id": 42,
  "email": "user@example.com",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_expires_at": "2026-02-24T12:34:56Z",
  "refresh_expires_in": 2592000
}

로그인

요청 예시:

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

응답 예시:

{
  "detail": "로그인 성공",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_expires_at": "2026-02-24T12:34:56Z",
  "refresh_expires_in": 2592000,
  "id": 42,
  "nickname": "귀여운토끼123",
  "name": "홍길동",
  "type": 2,
  "role": 30,
  "parent_user_id": null
}

소셜 로그인

슬롯 (Slots)

슬롯 생성

응답 예시:

{
  "detail": "광고주가 슬롯 2개 생성 성공",
  "created_slot_ids": [101, 102],
  "slot_count": 2
}

슬롯 목록 조회

슬롯 삭제 (복수)

{ "slot_ids": [101, 102, 103] }

슬롯 그룹 & 북마크 (Slot Groups & Bookmarks)

슬롯 그룹 생성

요청 예시:

{
  "platform_name": "naver",
  "name": "A급 상품",
  "color": "#ff6b6b",
  "description": "주력 상품 그룹"
}

슬롯 그룹 목록

슬롯 그룹 상세

슬롯 그룹 수정

슬롯 그룹 삭제

슬롯을 그룹에 추가

요청 예시:

{
  "slot_ids": [101, 102, 103]
}

슬롯을 그룹에서 제거

슬롯 북마크 설정/해제

요청 예시:

{
  "is_bookmarked": true
}

구독 (Subscriptions)

구독 플랜 목록

구독 생성

구독 갱신

구독 수정

구독 취소

구독 요약 조회

게시판 (Boards)

공지사항 목록

공지사항 생성 (관리자)

커뮤니티 게시글 목록

커뮤니티 게시글 작성

홍보 게시글 작성

댓글 작성

좋아요 토글

배너 목록 (노출용)

알림 시스템 (Notifications)

디바이스 토큰 등록 (모바일 - iOS/iPadOS)

요청 예시:

{
  "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "env": "prod",
  "device_name": "iPhone 14 Pro",
  "device_model": "iPhone15,2",
  "os_version": "iOS 17.2",
  "app_version": "1.0.0"
}

등록된 기기 목록

디바이스 토큰 삭제

PC/웹 세션 등록

요청 예시:

{
  "browser": "Chrome",
  "os": "Windows 10",
  "device_type": "desktop"
}

PC/웹 세션 이력

알림 발송 이력

알림 발송 전략: - ✅ 모든 활성 기기에 발송 (APNs 무료) - ✅ Thread ID로 중복 알림 그룹핑 - ✅ 우선순위별 차등 발송 (CRITICAL/HIGH/NORMAL/LOW) - ✅ 만료된 토큰 자동 비활성화

iOS 앱 개발자를 위한 가이드

1. 네트워크 라이브러리 설정

URLSession 사용 예시

import Foundation

class APIClient {
    static let shared = APIClient()
    private let baseURL = "https://rankly.kr/api/v1"
    private var accessToken: String?

    func setAccessToken(_ token: String) {
        self.accessToken = token
    }

    func request<T: Decodable>(
        endpoint: String,
        method: String = "GET",
        body: Data? = nil
    ) async throws -> T {
        guard let url = URL(string: "\(baseURL)\(endpoint)") else {
            throw APIError.invalidURL
        }

        var request = URLRequest(url: url)
        request.httpMethod = method
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        if let token = accessToken {
            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }

        if let body = body {
            request.httpBody = body
        }

        let (data, response) = try await URLSession.shared.data(for: request)

        guard let httpResponse = response as? HTTPURLResponse else {
            throw APIError.invalidResponse
        }

        guard (200...299).contains(httpResponse.statusCode) else {
            throw APIError.httpError(statusCode: httpResponse.statusCode)
        }

        let decoder = JSONDecoder()
        decoder.dateDecodingStrategy = .iso8601
        return try decoder.decode(T.self, from: data)
    }
}

2. 로그인 및 토큰 관리

struct LoginRequest: Codable {
    let email: String
    let password: String
}

struct LoginResponse: Codable {
    let access: String
    let refresh: String
}

func login(email: String, password: String) async throws {
    let request = LoginRequest(email: email, password: password)
    let body = try JSONEncoder().encode(request)

    let response: LoginResponse = try await APIClient.shared.request(
        endpoint: "/accounts/login/",
        method: "POST",
        body: body
    )

    // 토큰 저장
    APIClient.shared.setAccessToken(response.access)
    UserDefaults.standard.set(response.refresh, forKey: "refreshToken")
}

3. 슬롯 생성 예시

struct SlotCreateRequest: Codable {
    let advertiser_id: Int
    let platform_id: Int
    let keyword: String?
    let url: String?
    let slot_cnt: Int
    let start_date: String?  // "YYYY-MM-DD" 형식
    let end_date: String?    // "YYYY-MM-DD" 형식, 선택사항 (미지정 시 무기한)
}

struct SlotCreateResponse: Codable {
    let detail: String
    let created_ids: [Int]?
}

func createSlot(request: SlotCreateRequest) async throws -> SlotCreateResponse {
    let body = try JSONEncoder().encode(request)

    return try await APIClient.shared.request(
        endpoint: "/slots/user/create",
        method: "POST",
        body: body
    )
}

4. 게시판 게시글 조회 예시

struct PostListResponse: Codable {
    let items: [Post]
    let total: Int
    let page: Int
    let page_size: Int
}

struct Post: Codable {
    let id: Int
    let title: String
    let content: String
    let author: Author
    let likes_count: Int
    let comments_count: Int
    let created_at: String
}

func getCommunityPosts(
    page: Int = 1,
    pageSize: Int = 20,
    sort: String = "latest"
) async throws -> PostListResponse {
    let endpoint = "/boards/community/posts/?page=\(page)&page_size=\(pageSize)&sort=\(sort)"
    return try await APIClient.shared.request(endpoint: endpoint)
}

5. 에러 처리

enum APIError: Error {
    case invalidURL
    case invalidResponse
    case httpError(statusCode: Int)
    case decodingError(Error)
    case unauthorized
    case forbidden
    case notFound
    case serverError

    var localizedDescription: String {
        switch self {
        case .invalidURL:
            return "잘못된 URL입니다."
        case .invalidResponse:
            return "잘못된 응답입니다."
        case .httpError(let code):
            return "HTTP 오류: \(code)"
        case .decodingError(let error):
            return "데이터 파싱 오류: \(error.localizedDescription)"
        case .unauthorized:
            return "인증이 필요합니다."
        case .forbidden:
            return "권한이 없습니다."
        case .notFound:
            return "리소스를 찾을 수 없습니다."
        case .serverError:
            return "서버 오류가 발생했습니다."
        }
    }
}

6. 날짜 형식

7. 페이지네이션

대부분의 목록 API는 페이지네이션을 지원합니다: - page: 페이지 번호 (기본값: 1) - page_size: 페이지당 항목 수 (기본값: 20)

8. 정렬 옵션

게시판 목록 API는 다음 정렬 옵션을 지원합니다: - latest: 최신순 (기본값) - likes: 좋아요순 - comments: 댓글순 - views: 조회순

9. 이미지 업로드

이미지가 필요한 경우: - 방법 1: 이미지 URL 제공 (HTTPS, jpg/png만 허용) - 방법 2: Base64 인코딩 (향후 지원 예정)

10. Swagger UI 활용 팁

  1. 엔드포인트 탐색: Swagger UI에서 모든 엔드포인트를 카테고리별로 확인 가능
  2. 스키마 확인: 각 엔드포인트의 요청/응답 스키마를 확인하여 Swift 모델 작성
  3. 예시 값 확인: Swagger UI에서 제공하는 예시 값을 참고하여 테스트
  4. 에러 코드 확인: 각 엔드포인트의 가능한 에러 응답 확인

추가 리소스

유용한 링크

문의

API 관련 문의사항이 있으시면 개발팀에 연락해주세요.