跳到主要内容

📌 API Detail Design Document

1. API Information​

  • API Name: Collect pull request data
  • Module/Service: amdp-ags-dashboard-backend
  • Author: Reus
  • Created Date: 2025/08/18
  • Last Updated: 2025/08/18

2. Overview​

  • Purpose: API collect data branches on git server
  • Description: Collect branch data

3. Endpoint Specification​

  • Method: POST
  • URL: /dashboard/collect/pull-request
  • Headers:
    • Authorization: Bearer <token user>
    • Content-Type: application/json

Query Params​

NameTypeRequiredDescriptionExample

Path Params​

NameTypeRequiredDescriptionExample

Request Body​

{
  "branch": "main",
  "collectFrom": "2024-12-01",
  "collectTo": "2024-12-15",
  "host": "https://github.com",
  "organizationId": "org456",
  "projectId": 14245,
  "projectName": "My Project",
  "repositoryId": "repo123",
  "repositoryName": "example-repo",
  "token": "ghp_exampletoken123",
  "tool": "GIT"
}

4. Response Specification​

Success Response (200/201)​

{"code": 200,"message": "Success"}

Error Response (400/401/404/500)​

{"code": 400,"message": "Bad Request"}

5. Sequence / Flow (Source-PUML)​

@startuml
actor Client
participant "Dashboard Service" as DS
participant "Git Provider (GitHub)" as Git
database "MongoDB\ngitPullRequestCollection" as DB


Client -> DS: POST /collectPullRequestData\n{repo, collectFrom, collectTo, ...}
activate DS


DS -> DS: Parse & validate request


DS -> Git: Fetch pull request data\n(using token, repo info)
activate Git
Git --> DS: Pull request data (JSON)
deactivate Git


DS -> DS: Transform & prepare data


DS -> DB: Insert pull request data
activate DB
DB --> DS: Ack (insert success)
deactivate DB


DS --> Client: 200 OK\n{ "message": "Collect success" }
deactivate DS
@enduml

6. Sequence / Flow (Image)​

7. Dependencies​

  • DB tables:
{
"_id": {"$oid": "6697413bba38fa3fb6e90544"},
"_class": "com.amdp.dashboard.entity.mongodb.gitprovider.common.GitPullRequestCollection",
"authorUsername": "zzonsang",
"closedAt": {"$date": "2024-06-21T00:38:07.000Z"},
"commits": [
{
"organizationId": "amdp-owner",
"repositoryId": "844",
"repositoryName": "amdp-awesome-shopping-demo-account",
"commitId": "8725e55804380ee3fed2f3d490de3c0937f16d1a",
"authorName": "zzonsang",
"authorEmail": "zzonsang2@gmail.com",
"authoredDate": {"$date": "2024-06-21T00:37:42.000Z"},
"committerName": "zzonsang",
"committerEmail": "zzonsang2@gmail.com",
"committerDate": {"$date": "2024-06-21T00:37:42.000Z"},
"title": "[AMDP-101] PR1",
"message": "[AMDP-101] PR1",
"branches": ["feature/PR1", "main"],
"stats": {
"total": 1,
"additions": 1,
"deletions": 0
},
"fileChanges": [
{
"filename": "pr.txt",
"status": "added",
"additions": 1,
"deletions": 0,
"changes": 1
}
]
}
],
"createdAt": {"$date": "2024-06-21T00:38:01.000Z"},
"createdDate": {"$date": "2024-07-17T03:57:47.852Z"},
"gitProvider": "GITHUB",
"lastModifiedDate": {"$date": "2024-07-17T03:57:47.852Z"},
"locked": false,
"mergeCommitSha": "36a1e581ab3e3e1b86c22045a03b7dc49bb9761b",
"mergedAt": {"$date": "2024-06-21T00:38:07.000Z"},
"number": 1,
"organizationId": "amdp-owner",
"pullRequestId": "1931930615",
"pullRequestUrl": "https://github.com/amdp-owner/amdp-awesome-shopping-demo-account/pull/1",
"repositoryId": "844",
"repositoryName": "amdp-awesome-shopping-demo-account",
"requestedReviewers": [],
"sourceBranch": "feature/PR1",
"state": "closed",
"targetBranch": "main",
"title": "[AMDP-101] PR1",
"updatedAt": {"$date": "2024-06-21T00:38:07.000Z"}
}
  • External service call:
  • Message broker/topic:

8. Security & Performance Considerations​

  • Authentication & Authorization
  • Rate limit / Throttling
  • Caching
  • Timeout & Retry logic

9. Test Cases (basic)​

CaseInputExpected OutputNotes
Valid request{...}200 + data
Missing param{}400 error
Unauthorized401 error

10. Change History​

VersionDateAuthorChange