DataOps 서버가 구현할 API 3개

플랫폼에 기준 URL 하나를 등록하면 플랫폼이 그 아래 세 경로를 호출. 예시의 기준 URL 은 https://data.example.com/api.

경로 형식은 위 형식 고정. 대신 응답의 필드 이름은 제공 측 규칙을 따라도 무방. 플랫폼은 의미가 같은 여러 이름을 인식(아래 필드 별칭).

공통 규약#

1. 데이터셋 목록#

curl -H "Authorization: Bearer $TOKEN" \
  "https://data.example.com/api/datasets?page=1&page_size=50&updated_after=2026-07-01T00:00:00Z"

{
  "items": [
    {
      "id": "ds-inspect-2026w29",
      "name": "라인 검사 이미지 2026-W29",
      "modality": "image",
      "file_count": 412,
      "size_bytes": 1073741824,
      "updated_at": "2026-07-21T09:30:00Z"
    }
  ],
  "page": 1,
  "total": 3
}

• 플랫폼은 page(1부터) 전송. page_size 는 연결 확인(page=1&page_size=1)과, 플랫폼 API 호출자가 값을 지정할 때만 추가. 화면의 원격 데이터셋 목록은 page 만 전송.
• 페이지를 나눠 반환하면 total 반드시 포함. 화면은 불러온 항목 수가 total 보다 적을 때만 "더 불러오기" 로 다음 page 요청. total 이 없으면 첫 응답의 항목 수를 전체 개수로 간주하므로 두 번째 페이지부터는 표시되지 않음. 나누지 않으면 page · page_size 를 무시하고 전체 반환 가능.
• updated_after 가 지정되면 그 시각 이후 변경된 항목만 반환(권장). 화면은 이 값을 전송하지 않고, 스크립트가 GET /api/v1/external-sources/{id}/remote-datasets?updated_after=… 로 호출할 때만 UTC(…Z)로 전달.
• 동기화는 목록을 호출하지 않음. 매니페스트와 파일 경로만 사용.

2. 매니페스트#

curl -H "Authorization: Bearer $TOKEN" \
  "https://data.example.com/api/datasets/ds-inspect-2026w29/manifest"

{
  "dataset_id": "ds-inspect-2026w29",
  "name": "라인 검사 이미지 2026-W29",
  "modality": "image",
  "updated_at": "2026-07-21T09:30:00Z",
  "annotation_format": "coco",
  "classes": [{ "id": 0, "name": "defect_a" }, { "id": 1, "name": "defect_b" }],
  "files": [
    {
      "file_id": "f-0001",
      "filename": "20260721_line3_0001.png",
      "kind": "image",
      "size_bytes": 2493833,
      "sha256": "9f8a1c…",
      "meta": { "line": "line-3", "measured_at": "2026-07-21T09:30:12+09:00" }
    }
  ]
}

file_id 나 filename 이 없는 항목이 하나라도 있으면 매니페스트 전체를 읽지 못하고, 그 동기화는 실패.

3. 파일 본문#

curl -H "Authorization: Bearer $TOKEN" -o 0001.png \
  "https://data.example.com/api/datasets/ds-inspect-2026w29/files/f-0001"

• 파일 본문을 그대로 스트리밍. Content-Type 제한 없음.
• 플랫폼이 리다이렉트를 따르므로, 본문 대신 presigned URL 로 302 반환 가능. 다른 호스트로 리다이렉트되면 Authorization 헤더를 전송하지 않으므로, presigned URL 은 토큰 없이 다운로드 가능해야 함.
• 이어받기(Range)는 아직 미사용. 실패한 파일은 다음 동기화에서 전체를 다시 내려받음.
• 파일 하나는 2 GiB 까지(서버 설정으로 변경 가능). 초과하는 파일은 내려받는 도중에 중단하고 경고로 기록.

오류 응답#

// 401
{ "error": "invalid_token", "message": "토큰이 만료되었습니다." }
// 404
{ "error": "dataset_not_found", "message": "ds-xxxx 를 찾을 수 없습니다." }
// 429
{ "error": "rate_limited", "message": "잠시 후 다시 시도해 주십시오." }

플랫폼은 이 본문을 해석하지 않고 앞부분을 사용자에게 표시. 원인을 알 수 있는 한 문장 포함 필요.

플랫폼은 오류 응답을 재시도하지 않고 Retry-After 도 읽지 않음. 파일 호출이 실패하면 그 파일만 경고로 기록되고 다음 동기화에서 다시 내려받음. 매니페스트 호출이 실패하면 그 동기화 실패.

필드 별칭#

응답 필드 이름은 아래 중 어느 것이든 사용 가능. 앞에 있는 이름부터 찾고, 비어 있지 않은 첫 값 사용.

이 표에 없는 이름이 반드시 필요하면 플랫폼 팀에 별칭 추가 요청.

지원하는 파일 형식#

CSV · TSV · Parquet 는 확장자로 시계열과 표 구분 불가. 매니페스트의 파일별 kind 를 timeseries 나 tabular 로 지정하면 그 값을 따름. 지정하지 않으면 데이터셋 모달리티로 결정(tabular 면 표, 그 밖에는 시계열). 이때는 목록의 modality 를 tabular 로 지정하거나, 데이터셋 생성 시 모달리티 직접 선택 필요.

연동 확인 체크리스트 (제공 측)#

플랫폼에 등록하기 전에 curl 로 세 경로를 직접 호출해 확인. 명령은 참조 구현의 "실행 예시" 와 동일. 플랫폼의 연결 확인 은 목록만 호출하므로, 매니페스트와 파일 경로는 여기서 확인.