Taskify API 명세서

개요

이 문서는 Taskify 애플리케이션의 API 명세를 설명합니다.

• 버전: 1.0.0
• Swagger URL: https://sp-taskify-api.vercel.app/docs

API 엔드포인트

Auth

로그인

• POST /{teamId}/auth/login
• 설명: 사용자 로그인을 처리합니다.
• Request Body:

  {
    email: string;
    password: string;
  }

• Response:

  {
    user: {
      id: number;
      email: string;
      nickname: string;
      profileImageUrl: string | null;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
    }
    accessToken: string;
  }

비밀번호 변경

• PUT /{teamId}/auth/password
• 설명: 로그인한 사용자의 비밀번호를 변경합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    password: string;
    newPassword: string;
  }

• Response: 204 No Content

Cards

카드 생성

• POST /{teamId}/cards
• 설명: 새로운 카드를 생성합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    assigneeUserId?: number;
    dashboardId: number;
    columnId: number;
    title: string;
    description: string;
    dueDate?: string;
    tags?: string[];
    imageUrl?: string;
  }

• Response:

  {
    id: number;
    title: string;
    description: string;
    tags: string[];
    dueDate: string | null;
    assignee: {
      profileImageUrl: string | null;
      nickname: string;
      id: number;
    } | null;
    imageUrl: string | null;
    teamId: string;
    columnId: number;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
  }

카드 목록 조회

• GET /{teamId}/cards
• 설명: 특정 컬럼의 카드 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    size?: number; // 기본값: 10
    cursorId?: number;
    columnId: number;
  }

• Response:

  {
    cursorId: number | null;
    totalCount: number;
    cards: Array<{
      id: number;
      title: string;
      description: string;
      tags: string[];
      dueDate: string | null;
      assignee: {
        profileImageUrl: string | null;
        nickname: string;
        id: number;
      } | null;
      imageUrl: string | null;
      teamId: string;
      columnId: number;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
    }>;
  }

카드 상세 조회

• GET /{teamId}/cards/{cardId}
• 설명: 특정 카드의 상세 정보를 조회합니다.
• 인증: Bearer 토큰 필요
• Response:

  {
    id: number;
    title: string;
    description: string;
    tags: string[];
    dueDate: string | null;
    assignee: {
      profileImageUrl: string | null;
      nickname: string;
      id: number;
    } | null;
    imageUrl: string | null;
    teamId: string;
    columnId: number;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
  }

카드 수정

• PUT /{teamId}/cards/{cardId}
• 설명: 특정 카드의 정보를 수정합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    columnId?: number;
    assigneeUserId?: number | null;
    title?: string;
    description?: string;
    dueDate?: string | null;
    tags?: string[];
    imageUrl?: string | null;
  }

• Response: 카드 상세 조회와 동일한 형식

카드 삭제

• DELETE /{teamId}/cards/{cardId}
• 설명: 특정 카드를 삭제합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

Columns

컬럼 생성

• POST /{teamId}/columns
• 설명: 새로운 컬럼을 생성합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    title: string;
    dashboardId: number;
  }

• Response:

  {
    id: number;
    title: string;
    teamId: string;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
  }

컬럼 목록 조회

• GET /{teamId}/columns
• 설명: 특정 대시보드의 컬럼 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    dashboardId: number;
  }

• Response:

  {
    result: "SUCCESS";
    data: Array<{
      id: number;
      title: string;
      teamId: string;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
    }>;
  }

컬럼 수정

• PUT /{teamId}/columns/{columnId}
• 설명: 특정 컬럼의 정보를 수정합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    title: string;
  }

• Response: 컬럼 생성과 동일한 형식

컬럼 삭제

• DELETE /{teamId}/columns/{columnId}
• 설명: 특정 컬럼을 삭제합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

카드 이미지 업로드

• POST /{teamId}/columns/{columnId}/card-image
• 설명: 컬럼에 카드 이미지를 업로드합니다.
• 인증: Bearer 토큰 필요
• Request Body: multipart/form-data (image 필드)
• Response:

  {
    imageUrl: string;
  }

Comments

댓글 생성

• POST /{teamId}/comments
• 설명: 새로운 댓글을 생성합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    content: string;
    cardId: number;
    columnId: number;
    dashboardId: number;
  }

• Response:

  {
    id: number;
    content: string;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
    cardId: number;
    author: {
      profileImageUrl: string | null;
      nickname: string;
      id: number;
    }
  }

댓글 목록 조회

• GET /{teamId}/comments
• 설명: 특정 카드의 댓글 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    size?: number; // 기본값: 10
    cursorId?: number;
    cardId: number;
  }

• Response:

  {
    cursorId: number | null;
    comments: Array<{
      id: number;
      content: string;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
      cardId: number;
      author: {
        profileImageUrl: string | null;
        nickname: string;
        id: number;
      };
    }>;
  }

댓글 수정

• PUT /{teamId}/comments/{commentId}
• 설명: 특정 댓글의 내용을 수정합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    content: string;
  }

• Response: 댓글 생성과 동일한 형식

댓글 삭제

• DELETE /{teamId}/comments/{commentId}
• 설명: 특정 댓글을 삭제합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

Dashboards

대시보드 생성

• POST /{teamId}/dashboards
• 설명: 새로운 대시보드를 생성합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    title: string;
    color: string;
  }

• Response:

  {
    id: number;
    title: string;
    color: string;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
    createdByMe: boolean;
    userId: number;
  }

대시보드 목록 조회

• GET /{teamId}/dashboards
• 설명: 대시보드 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    navigationMethod: "infiniteScroll" | "pagination";
    cursorId?: number;
    page?: number; // 기본값: 1
    size?: number; // 기본값: 10
  }

• Response:

  {
    cursorId: number | null;
    totalCount: number;
    dashboards: Array<{
      id: number;
      title: string;
      color: string;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
      createdByMe: boolean;
      userId: number;
    }>;
  }

대시보드 상세 조회

• GET /{teamId}/dashboards/{dashboardId}
• 설명: 특정 대시보드의 상세 정보를 조회합니다.
• 인증: Bearer 토큰 필요
• Response: 대시보드 생성과 동일한 형식

대시보드 수정

• PUT /{teamId}/dashboards/{dashboardId}
• 설명: 특정 대시보드의 정보를 수정합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    title?: string;
    color?: string;
  }

• Response: 대시보드 생성과 동일한 형식

대시보드 삭제

• DELETE /{teamId}/dashboards/{dashboardId}
• 설명: 특정 대시보드를 삭제합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

대시보드 초대 생성

• POST /{teamId}/dashboards/{dashboardId}/invitations
• 설명: 특정 대시보드에 사용자를 초대합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    email: string;
  }

• Response:

  {
    id: number;
    inviter: {
      nickname: string;
      email: string;
      id: number;
    }
    teamId: string;
    dashboard: {
      title: string;
      id: number;
    }
    invitee: {
      nickname: string;
      email: string;
      id: number;
    }
    inviteAccepted: boolean | null;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
  }

대시보드 초대 목록 조회

• GET /{teamId}/dashboards/{dashboardId}/invitations
• 설명: 특정 대시보드의 초대 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    page?: number; // 기본값: 1
    size?: number; // 기본값: 10
  }

• Response:

  {
    totalCount: number;
    invitations: Array<{
      id: number;
      inviter: {
        nickname: string;
        email: string;
        id: number;
      };
      teamId: string;
      dashboard: {
        title: string;
        id: number;
      };
      invitee: {
        nickname: string;
        email: string;
        id: number;
      };
      inviteAccepted: boolean | null;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
    }>;
  }

대시보드 초대 취소

• DELETE /{teamId}/dashboards/{dashboardId}/invitations/{invitationId}
• 설명: 특정 초대를 취소합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

Invitations

내가 받은 초대 목록 조회

• GET /{teamId}/invitations
• 설명: 현재 사용자가 받은 초대 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    size?: number; // 기본값: 10
    cursorId?: number;
    title?: string;
  }

• Response:

  {
    cursorId: number | null;
    invitations: Array<{
      id: number;
      inviter: {
        nickname: string;
        email: string;
        id: number;
      };
      teamId: string;
      dashboard: {
        title: string;
        id: number;
      };
      invitee: {
        nickname: string;
        email: string;
        id: number;
      };
      inviteAccepted: boolean | null;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
    }>;
  }

초대 응답

• PUT /{teamId}/invitations/{invitationId}
• 설명: 받은 초대에 대해 수락 또는 거절 응답을 합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    inviteAccepted: boolean;
  }

• Response: 대시보드 초대 생성과 동일한 형식

Members

대시보드 멤버 목록 조회

• GET /{teamId}/members
• 설명: 특정 대시보드의 멤버 목록을 조회합니다.
• 인증: Bearer 토큰 필요
• Query Parameters:

  {
    page?: number; // 기본값: 1
    size?: number; // 기본값: 20
    dashboardId: number;
  }

• Response:

  {
    members: Array<{
      id: number;
      userId: number;
      email: string;
      nickname: string;
      profileImageUrl: string | null;
      createdAt: string; // ISO 8601 형식의 날짜
      updatedAt: string; // ISO 8601 형식의 날짜
      isOwner: boolean;
    }>;
    totalCount: number;
  }

대시보드 멤버 삭제

• DELETE /{teamId}/members/{memberId}
• 설명: 특정 대시보드에서 멤버를 삭제합니다.
• 인증: Bearer 토큰 필요
• Response: 204 No Content

Users

회원가입

• POST /{teamId}/users
• 설명: 새로운 사용자 계정을 생성합니다.
• Request Body:

  {
    email: string;
    nickname: string;
    password: string;
  }

• Response:

  {
    id: number;
    email: string;
    nickname: string;
    profileImageUrl: string | null;
    createdAt: string; // ISO 8601 형식의 날짜
    updatedAt: string; // ISO 8601 형식의 날짜
  }

내 정보 조회

• GET /{teamId}/users/me
• 설명: 현재 로그인한 사용자의 정보를 조회합니다.
• 인증: Bearer 토큰 필요
• Response: 회원가입 응답과 동일한 형식

내 정보 수정

• PUT /{teamId}/users/me
• 설명: 현재 로그인한 사용자의 정보를 수정합니다.
• 인증: Bearer 토큰 필요
• Request Body:

  {
    nickname?: string;
    profileImageUrl?: string | null;
  }

• Response: 회원가입 응답과 동일한 형식

프로필 이미지 업로드

• POST /{teamId}/users/me/image
• 설명: 사용자의 프로필 이미지를 업로드합니다.
• 인증: Bearer 토큰 필요
• Request Body: multipart/form-data (image 필드)
• Response:

  {
    profileImageUrl: string;
  }

에러 응답

대부분의 API 엔드포인트는 에러 발생 시 다음과 같은 형식의 응답을 반환합니다:

{
  message: string;
}

주요 HTTP 상태 코드:

• 400: 잘못된 요청
• 401: 인증 실패
• 403: 권한 없음
• 404: 리소스를 찾을 수 없음
• 409: 충돌 (예: 중복된 이메일)