hansoo/Obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
266674cc0e776bfee8da7c151563a146ab68ddcc
Obsidian/ZELLYY/zellyy note/02_기술_문서/API_명세서.md
hansoo 266674cc0e 초기 커밋
2025-03-26 18:16:46 +09:00

11 KiB
Raw Blame History

Zellyy API 명세서

이 문서는 Zellyy 프로젝트의 API 엔드포인트와 기능에 대한 상세 명세를 제공합니다.

기본 정보

  • 기본 URL: https://a11.ism.kr/api
  • API 버전: v1
  • 인증 방식: JWT 토큰 (Bearer Authentication)
  • 응답 형식: JSON

인증 API

회원가입

POST /auth/signup

요청 본문:

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

응답 (200 OK):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "username"
  },
  "session": {
    "access_token": "jwt_token",
    "refresh_token": "refresh_token",
    "expires_at": 1672531200
  }
}

로그인

POST /auth/login

요청 본문:

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

응답 (200 OK):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "username"
  },
  "session": {
    "access_token": "jwt_token",
    "refresh_token": "refresh_token",
    "expires_at": 1672531200
  }
}

토큰 갱신

POST /auth/refresh

요청 본문:

{
  "refresh_token": "refresh_token"
}

응답 (200 OK):

{
  "access_token": "new_jwt_token",
  "refresh_token": "new_refresh_token",
  "expires_at": 1672531200
}

로그아웃

POST /auth/logout

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "message": "Successfully logged out"
}

사용자 API

사용자 정보 조회

GET /users/me

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "id": "uuid",
  "email": "user@example.com",
  "username": "username",
  "display_name": "Display Name",
  "avatar_url": "https://example.com/avatar.jpg",
  "is_premium": false,
  "premium_until": null,
  "created_at": "2023-01-01T00:00:00Z"
}

사용자 정보 업데이트

PATCH /users/me

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "display_name": "New Display Name",
  "avatar_url": "https://example.com/new-avatar.jpg"
}

응답 (200 OK):

{
  "id": "uuid",
  "email": "user@example.com",
  "username": "username",
  "display_name": "New Display Name",
  "avatar_url": "https://example.com/new-avatar.jpg",
  "updated_at": "2023-01-02T00:00:00Z"
}

카드 API

카드 생성

POST /cards

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "content": "This is a card content",
  "background_color": "#FFFFFF",
  "text_color": "#000000",
  "font_family": "system",
  "font_size": 16,
  "text_align": "center",
  "is_public": false,
  "tags": ["personal", "ideas"]
}

응답 (201 Created):

{
  "id": "uuid",
  "content": "This is a card content",
  "background_color": "#FFFFFF",
  "text_color": "#000000",
  "font_family": "system",
  "font_size": 16,
  "text_align": "center",
  "is_public": false,
  "is_synced": false,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "tags": ["personal", "ideas"]
}

카드 목록 조회

GET /cards

요청 헤더:

Authorization: Bearer jwt_token

쿼리 파라미터:

  • page: 페이지 번호 (기본값: 1)
  • limit: 페이지당 항목 수 (기본값: 20, 최대: 100)
  • sort: 정렬 기준 (options: created_at, updated_at, 기본값: created_at)
  • order: 정렬 순서 (options: asc, desc, 기본값: desc)
  • tag: 태그로 필터링 (선택 사항)
  • search: 내용 검색 (선택 사항)

응답 (200 OK):

{
  "data": [
    {
      "id": "uuid1",
      "content": "Card 1 content",
      "background_color": "#FFFFFF",
      "text_color": "#000000",
      "font_family": "system",
      "font_size": 16,
      "text_align": "center",
      "is_public": false,
      "is_synced": false,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z",
      "tags": ["personal"]
    },
    {
      "id": "uuid2",
      "content": "Card 2 content",
      "background_color": "#F0F0F0",
      "text_color": "#333333",
      "font_family": "arial",
      "font_size": 18,
      "text_align": "left",
      "is_public": true,
      "is_synced": true,
      "created_at": "2023-01-02T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z",
      "tags": ["ideas", "public"]
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "total_pages": 3
  }
}

카드 상세 조회

GET /cards/{card_id}

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "id": "uuid",
  "content": "This is a card content",
  "background_color": "#FFFFFF",
  "text_color": "#000000",
  "font_family": "system",
  "font_size": 16,
  "text_align": "center",
  "is_public": false,
  "is_synced": false,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "tags": ["personal", "ideas"],
  "share_count": 2,
  "share_platforms": ["facebook", "instagram"]
}

카드 업데이트

PATCH /cards/{card_id}

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "content": "Updated card content",
  "background_color": "#F0F0F0",
  "is_public": true,
  "tags": ["personal", "ideas", "updated"]
}

응답 (200 OK):

{
  "id": "uuid",
  "content": "Updated card content",
  "background_color": "#F0F0F0",
  "text_color": "#000000",
  "font_family": "system",
  "font_size": 16,
  "text_align": "center",
  "is_public": true,
  "is_synced": false,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-02T00:00:00Z",
  "tags": ["personal", "ideas", "updated"]
}

카드 삭제

DELETE /cards/{card_id}

요청 헤더:

Authorization: Bearer jwt_token

응답 (204 No Content)

소셜 공유 API

소셜 계정 연동

POST /social/connect/{platform}

지원 플랫폼: facebook, instagram, twitter

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "access_token": "platform_access_token",
  "refresh_token": "platform_refresh_token",
  "expires_at": 1672531200
}

응답 (200 OK):

{
  "platform": "facebook",
  "connected": true,
  "platform_user_id": "platform_user_id",
  "expires_at": 1672531200
}

소셜 계정 연동 해제

DELETE /social/connect/{platform}

요청 헤더:

Authorization: Bearer jwt_token

응답 (204 No Content)

연동된 소셜 계정 목록

GET /social/accounts

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "accounts": [
    {
      "platform": "facebook",
      "platform_user_id": "facebook_user_id",
      "connected_at": "2023-01-01T00:00:00Z",
      "expires_at": 1672531200
    },
    {
      "platform": "instagram",
      "platform_user_id": "instagram_user_id",
      "connected_at": "2023-01-02T00:00:00Z",
      "expires_at": 1672617600
    }
  ]
}

카드 소셜 공유

POST /cards/{card_id}/share/{platform}

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "message": "Check out my new card!" // 선택적 메시지
}

응답 (200 OK):

{
  "id": "share_id",
  "card_id": "card_id",
  "platform": "facebook",
  "status": "success",
  "share_url": "https://facebook.com/post/123456",
  "shared_at": "2023-01-01T00:00:00Z"
}

구독 API

구독 플랜 목록

GET /subscriptions/plans

응답 (200 OK):

{
  "plans": [
    {
      "id": "monthly",
      "name": "Monthly Premium",
      "description": "Monthly subscription with cloud sync",
      "price": 4.99,
      "currency": "USD",
      "interval": "month",
      "features": [
        "Cloud sync",
        "Unlimited cards",
        "Premium templates"
      ]
    },
    {
      "id": "yearly",
      "name": "Yearly Premium",
      "description": "Yearly subscription with cloud sync (save 20%)",
      "price": 47.99,
      "currency": "USD",
      "interval": "year",
      "features": [
        "Cloud sync",
        "Unlimited cards",
        "Premium templates",
        "Priority support"
      ]
    }
  ]
}

구독 생성

POST /subscriptions

요청 헤더:

Authorization: Bearer jwt_token

요청 본문:

{
  "plan_id": "monthly",
  "payment_method_id": "payment_method_id",
  "payment_provider": "stripe"
}

응답 (201 Created):

{
  "id": "subscription_id",
  "plan_id": "monthly",
  "status": "active",
  "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-02-01T00:00:00Z",
  "payment_provider": "stripe",
  "payment_id": "payment_id"
}

현재 구독 정보

GET /subscriptions/current

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "id": "subscription_id",
  "plan_id": "monthly",
  "status": "active",
  "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-02-01T00:00:00Z",
  "auto_renew": true,
  "payment_provider": "stripe",
  "payment_id": "payment_id"
}

구독 취소

POST /subscriptions/cancel

요청 헤더:

Authorization: Bearer jwt_token

응답 (200 OK):

{
  "id": "subscription_id",
  "status": "canceled",
  "end_date": "2023-02-01T00:00:00Z",
  "message": "Subscription will be active until the end date"
}

오류 응답

모든 API 엔드포인트는 오류 발생 시 다음과 같은 형식으로 응답합니다:

응답 (4xx/5xx):

{
  "error": {
    "code": "error_code",
    "message": "Error message description",
    "details": {} // 추가 오류 정보 (선택 사항)
  }
}

공통 오류 코드

  • invalid_request: 잘못된 요청 형식
  • authentication_required: 인증 필요
  • invalid_credentials: 잘못된 인증 정보
  • permission_denied: 권한 없음
  • resource_not_found: 리소스를 찾을 수 없음
  • rate_limit_exceeded: 요청 한도 초과
  • internal_server_error: 서버 내부 오류

웹훅 (Webhook)

Zellyy는 다음 이벤트에 대한 웹훅을 제공합니다:

웹훅 등록

POST /webhooks

요청 헤더:

Authorization: Bearer admin_token

요청 본문:

{
  "url": "https://your-service.com/webhook",
  "events": ["user.created", "subscription.created", "subscription.canceled"],
  "secret": "your_webhook_secret"
}

응답 (201 Created):

{
  "id": "webhook_id",
  "url": "https://your-service.com/webhook",
  "events": ["user.created", "subscription.created", "subscription.canceled"],
  "created_at": "2023-01-01T00:00:00Z"
}

웹훅 이벤트 형식

{
  "id": "event_id",
  "type": "event.type",
  "created_at": "2023-01-01T00:00:00Z",
  "data": {
    // 이벤트 관련 데이터
  }
}

결론

이 API 명세서는 Zellyy 프로젝트의 기본 기능을 구현하기 위한 엔드포인트를 정의합니다. 프로젝트가 발전함에 따라 추가 엔드포인트와 기능이 확장될 수 있습니다.

Reference in New Issue View Git Blame Copy Permalink