Skip to content

API.md

Latest commit

 

History

History
308 lines (265 loc) · 5.98 KB

API.md

File metadata and controls

308 lines (265 loc) · 5.98 KB

BurnGuard — API 명세

Base URL

https://your-server:8082/api/v1

1. 팀 대시보드 API

GET /dashboard/team/{teamId} — 팀 전체 번아웃 현황

Response (200)

{
  "teamId": "backend-team",
  "members": [
    {
      "login": "developer1",
      "name": "김개발",
      "totalScore": 0.72,
      "riskLevel": "HIGH",
      "trendDirection": "INCREASING",
      "topRiskIndicator": "NIGHT_COMMIT",
      "lastUpdated": "2026-03-23T09:00:00Z"
    },
    {
      "login": "developer2",
      "name": "이코딩",
      "totalScore": 0.25,
      "riskLevel": "LOW",
      "trendDirection": "STABLE",
      "topRiskIndicator": null,
      "lastUpdated": "2026-03-23T09:00:00Z"
    }
  ],
  "teamAverage": 0.41,
  "teamRiskLevel": "MEDIUM",
  "alertCount": {
    "HIGH": 1,
    "CRITICAL": 0
  }
}

2. 개발자 상세 API

GET /dashboard/developer/{login} — 개발자별 Git 패턴 상세

Query Parameters:

  • days (default: 14): 분석 기간

Response (200)

{
  "login": "developer1",
  "name": "김개발",
  "analysisRange": {
    "from": "2026-03-09",
    "to": "2026-03-23"
  },
  "totalScore": 0.72,
  "riskLevel": "HIGH",
  "indicators": {
    "nightCommit": {
      "score": 0.85,
      "weight": 0.25,
      "detail": {
        "totalCommits": 47,
        "nightCommits": 18,
        "ratio": 0.383,
        "peakHour": 2
      }
    },
    "prStale": {
      "score": 0.60,
      "weight": 0.25,
      "detail": {
        "totalPrs": 5,
        "stalePrs": 2,
        "ratio": 0.40,
        "avgStaleHours": 96.5
      }
    },
    "reviewDelay": {
      "score": 0.45,
      "weight": 0.20,
      "detail": {
        "avgDelayHours": 21.6,
        "reviewsGiven": 8,
        "fastestResponseHours": 1.2,
        "slowestResponseHours": 48.0
      }
    },
    "commitDrop": {
      "score": 0.70,
      "weight": 0.20,
      "detail": {
        "thisWeekCommits": 6,
        "lastWeekCommits": 20,
        "dropRate": 0.70
      }
    },
    "weekendWork": {
      "score": 0.50,
      "weight": 0.10,
      "detail": {
        "weekendCommits": 7,
        "totalCommits": 47,
        "ratio": 0.149,
        "holidayCommits": 2
      }
    }
  },
  "baseline": {
    "personalMean": 0.35,
    "personalStdDev": 0.12,
    "threshold": 0.53,
    "isAboveThreshold": true
  }
}

GET /dashboard/developer/{login}/trends — 개발자 트렌드 (90일)

Response (200)

{
  "login": "developer1",
  "days": 90,
  "weeklyScores": [
    { "weekStart": "2026-01-05", "score": 0.28, "riskLevel": "LOW" },
    { "weekStart": "2026-01-12", "score": 0.35, "riskLevel": "MEDIUM" },
    { "weekStart": "2026-01-19", "score": 0.42, "riskLevel": "MEDIUM" },
    { "weekStart": "2026-03-16", "score": 0.72, "riskLevel": "HIGH" }
  ],
  "trendDirection": "INCREASING",
  "trendSlope": 0.05,
  "peakScore": { "week": "2026-03-16", "score": 0.72 }
}

3. Webhook 수신 API

POST /webhooks/github — GitHub Webhook

Headers:

  • X-Hub-Signature-256: HMAC-SHA256 서명
  • X-GitHub-Event: 이벤트 유형 (push, pull_request, pull_request_review)
  • X-GitHub-Delivery: 배송 ID

Response (200): 정상 수신

Response (401): HMAC 검증 실패

POST /webhooks/gitlab — GitLab Webhook

Headers:

  • X-Gitlab-Token: 설정된 시크릿 토큰
  • X-Gitlab-Event: 이벤트 유형

Response (200): 정상 수신

4. 알림 설정 API

GET /settings/notifications — 알림 설정 조회

Response (200)

{
  "teamId": "backend-team",
  "slackWebhookUrl": "https://hooks.slack.com/services/T.../B.../...",
  "alertThresholds": {
    "HIGH": true,
    "CRITICAL": true,
    "MEDIUM": false
  },
  "weeklyReportEnabled": true,
  "weeklyReportDay": "MONDAY",
  "weeklyReportTime": "09:00",
  "emailRecipients": ["lead@company.com"]
}

PUT /settings/notifications — 알림 설정 변경

Request

{
  "alertThresholds": {
    "HIGH": true,
    "CRITICAL": true,
    "MEDIUM": true
  },
  "weeklyReportEnabled": true,
  "weeklyReportDay": "MONDAY",
  "weeklyReportTime": "09:00"
}

5. 주간 리포트 API

GET /reports/weekly — 이번 주 리포트 조회

Response (200)

{
  "reportPeriod": {
    "from": "2026-03-16",
    "to": "2026-03-22"
  },
  "teamSummary": {
    "averageScore": 0.38,
    "previousWeekAverage": 0.32,
    "changeDirection": "INCREASING",
    "membersAtRisk": 1
  },
  "memberDetails": [
    {
      "login": "developer1",
      "score": 0.72,
      "riskLevel": "HIGH",
      "changeFromLastWeek": 0.15,
      "topContributor": "NIGHT_COMMIT"
    },
    {
      "login": "developer2",
      "score": 0.25,
      "riskLevel": "LOW",
      "changeFromLastWeek": -0.05,
      "topContributor": null
    }
  ],
  "recommendations": [
    "developer1의 심야 커밋 비율이 38%로 높습니다. 업무 시간 내 작업 배분을 확인해보세요.",
    "팀 전체 PR 리뷰 응답 시간이 평균 18시간입니다. 리뷰 우선순위를 높이는 것을 권장합니다."
  ]
}

POST /reports/weekly/send — 주간 리포트 수동 발송

Response (202)

{
  "message": "주간 리포트가 발송 대기열에 추가되었습니다."
}

6. Git 이벤트 조회 API

GET /events?login={login}&type={type}&from={date}&to={date}

Response (200)

{
  "events": [
    {
      "id": 1,
      "eventType": "PUSH",
      "authorLogin": "developer1",
      "timestamp": "2026-03-23T02:30:00Z",
      "repository": "company/backend-api",
      "commitCount": 3,
      "branch": "main"
    }
  ],
  "totalCount": 47,
  "page": 0,
  "size": 20
}

HTTP 상태 코드

코드 설명
200 성공
202 비동기 요청 접수
400 잘못된 요청
401 HMAC/토큰 검증 실패
404 리소스 없음
500 서버 오류

공통 에러 응답

{
  "code": "ERROR_CODE",
  "message": "에러 설명",
  "timestamp": "2026-03-23T09:00:00Z",
  "correlationId": "gh-delivery-abc123"
}