본문으로 건너뛰기

API 명세

최종 업데이트: 2025년 6월 29일

이 문서는 SurfAI 서비스의 뒤에서 일하는 프로그램(서버)이 어떤 기능들을 제공하고, 어떻게 정보를 주고받는지, 그리고 어떤 로그인 방식이 필요한지 자세히 설명해 드립니다.

1. 기본 정보​

  • 서버 주소 (실제 서비스): https://api.surfai.org
  • 서버 주소 (개발 중): http://localhost:3000
  • 로그인 방식: 모든 중요한 기능들은 HttpOnly 쿠키라는 안전한 방식으로 전달되는 JWT라는 로그인 정보(접근 토큰)를 통해 사용자를 확인합니다. 만약 Swagger라는 테스트 도구로 기능을 확인하려면, 'Authorize' 버튼에 Bearer <로그인 정보> 형식으로 로그인 정보를 입력해야 합니다.

2. 로그인 관련 기능​

담당: AuthController 기본 주소: /auth

2.1 일반 회원가입​

  • 주소: POST /register
  • 설명: 이메일, 비밀번호, 표시할 이름을 입력하여 새로운 사용자를 만듭니다.
  • 로그인 필요 여부: 필요 없음 (누구나 사용 가능)
  • 보내는 정보: CreateUserDTO (사용자 정보를 담는 양식)
  • 성공 시 응답 (201 Created): UserResponseDTO (만들어진 사용자 정보)
  • 실패 시 응답: 400 잘못된 요청, 409 이미 존재함

2.2 일반 로그인​

  • 주소: POST /login
  • 설명: 이메일과 비밀번호로 사용자가 맞는지 확인하고, 로그인 정보(접근 토큰과 갱신 토큰)를 HttpOnly 쿠키로 사용자 컴퓨터에 저장합니다.
  • 로그인 필요 여부: 필요 없음 (누구나 사용 가능)
  • 보내는 정보: LoginDTO (로그인 정보를 담는 양식)
  • 성공 시 응답 (200 OK): LoginResponseDTO (로그인 성공 정보)
  • 실패 시 응답: 401 권한 없음

2.3 Google 로그인 시작​

  • 주소: GET /google
  • 설명: 사용자를 Google 로그인 페이지로 연결해 줍니다.
  • 성공 시 응답 (302 Found): Google 로그인 페이지로 이동

2.4 Google 로그인 결과 처리​

  • 주소: GET /google/callback
  • 설명: Google 로그인이 성공한 후 Google에서 우리 서비스로 다시 연결해 주는 주소입니다. 로그인 처리가 끝나면 웹사이트 화면으로 다시 연결해 줍니다.
  • 성공 시 응답 (302 Found): 웹사이트 화면으로 이동

2.5 로그인 정보(토큰) 다시 받기​

  • 주소: POST /refresh
  • 설명: 만료된 로그인 정보(접근 토큰)를 새로운 갱신 토큰을 사용하여 다시 받습니다.
  • 로그인 필요 여부: 갱신 토큰 필요
  • 성공 시 응답 (200 OK): { "message": "로그인 정보가 성공적으로 갱신되었습니다." }

2.6 내 정보 보기​

  • 주소: GET /profile
  • 설명: 현재 로그인한 사용자의 자세한 정보를 보여줍니다.
  • 로그인 필요 여부: 접근 토큰 필요
  • 성공 시 응답 (200 OK): UserResponseDTO (사용자 정보)

2.7 로그아웃​

  • 주소: POST /logout
  • 설명: 사용자의 갱신 토큰을 무효화하고, 사용자 컴퓨터에 저장된 로그인 관련 쿠키를 삭제합니다.
  • 로그인 필요 여부: 접근 토큰 필요
  • 성공 시 응답 (204 No Content): 응답 내용 없음

3. 만들어진 그림/영상 기록 관련 기능​

담당: GeneratedOutputController 기본 주소: /my-outputs 로그인 필요 여부: 모든 기능은 접근 토큰이 필요합니다.

3.1 내가 만든 그림/영상 기록 목록 보기​

  • 주소: GET /
  • 추가 정보: page: 숫자, limit: 숫자 (몇 번째 페이지를 볼지, 한 페이지에 몇 개를 볼지)
  • 성공 시 응답 (200 OK): PaginatedHistoryResponse (페이지별 기록 목록)

3.2 그림/영상 미리 보기 주소 요청​

  • 주소: GET /:id/view-url
  • 설명: 특정 그림/영상을 웹사이트에서 미리 볼 수 있는 짧은 기간 동안만 유효한 주소를 요청합니다.
  • 성공 시 응답 (200 OK): { "viewUrl": "https://..." } (미리 보기 주소)

3.3 그림/영상 다운로드 주소 요청​

  • 주소: GET /:id/download-url
  • 설명: 특정 그림/영상을 다운로드할 수 있는 짧은 기간 동안만 유효한 주소를 요청합니다.
  • 성공 시 응답 (200 OK): { "downloadUrl": "https://..." } (다운로드 주소)

3.4 그림/영상 기록 삭제​

  • 주소: DELETE /:id
  • 설명: 특정 그림/영상 기록과 관련된 파일들을 삭제합니다.
  • 성공 시 응답 (204 No Content): 응답 내용 없음

4. 관리자 기능 - 그림/영상 만드는 방법(템플릿) 관리​

담당: AdminWorkflowController 기본 주소: /workflow-templates 로그인 필요 여부: 모든 기능은 접근 토큰과 관리자 권한이 필요합니다.

4.1 그림/영상 만드는 방법(템플릿) 종류 목록 보기​

  • 주소: GET /categories
  • 설명: 템플릿을 만들 때 사용할 수 있는 모든 종류(카테고리) 목록을 보여줍니다.
  • 성공 시 응답 (200 OK): string[] (종류 이름 목록)

4.2 설정 값 미리 정해진 목록 보기​

  • 주소: GET /parameter-presets
  • 추가 정보: category: 문자 (선택 사항, 특정 종류의 설정 값만 볼 때 사용)
  • 성공 시 응답 (200 OK): ParameterPreset[] (미리 정해진 설정 값 목록)

4.3 [1단계] 새로운 그림/영상 만드는 방법(템플릿) 만들기 (기본 틀)​

  • 주소: POST /
  • 설명: parameter_map을 제외한 템플릿의 기본 정보만 저장하여 틀을 만듭니다.
  • 보내는 정보: CreateWorkflowTemplateDTO (템플릿 기본 정보를 담는 양식)
  • 성공 시 응답 (201 Created): WorkflowTemplateResponseDTO (만들어진 템플릿 정보)

4.4 [2단계] 세부 설정 값 연결하기​

  • 주소: PUT /:id/parameter-map
  • 설명: 만들어진 템플릿에 사용자가 바꿀 수 있는 세부 설정 값들을 연결합니다. (기존 내용은 모두 바뀜)
  • 보내는 정보: Record<string, WorkflowParameterMappingItemDTO> (세부 설정 값들을 담는 양식)
  • 성공 시 응답 (200 OK): WorkflowTemplateResponseDTO (수정된 템플릿 정보)

4.5 그림/영상 만드는 방법(템플릿) 전체 수정​

  • 주소: PATCH /:id
  • 설명: 특정 템플릿의 모든 정보를 한 번에 수정합니다.
  • 보내는 정보: Partial<CreateWorkflowTemplateDTO & { parameter_map: ... }> (수정할 템플릿 정보를 담는 양식)
  • 성공 시 응답 (200 OK): WorkflowTemplateResponseDTO (수정된 템플릿 정보)

4.6 그림/영상 만드는 방법(템플릿) 목록 보기​

  • 주소: GET /
  • 성공 시 응답 (200 OK): WorkflowTemplateResponseDTO[] (템플릿 목록)

4.7 특정 그림/영상 만드는 방법(템플릿) 자세히 보기​

  • 주소: GET /:id
  • 성공 시 응답 (200 OK): WorkflowTemplateResponseDTO (자세한 템플릿 정보)

4.8 그림/영상 만드는 방법(템플릿) 삭제​

  • 주소: DELETE /:id
  • 성공 시 응답 (204 No Content): 응답 내용 없음