DataOps 쪽이 구현할 API 3개

플랫폼에 기준 URL 하나를 등록하면, 플랫폼은 그 아래의 세 경로를 부릅니다. 예시의 https://data.example.com/api 가 기준 URL 입니다.

경로 모양은 이대로여야 합니다. 대신 응답의 필드 이름은 여러분 규칙을 따라도 됩니다. 플랫폼은 뜻이 같은 여러 이름을 받아 줍니다(아래 필드 별칭).

공통 규약#

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 를 보냅니다. 지원하지 않으면 무시하고 전부 돌려줘도 됩니다. total 을 주면 화면이 "더 불러오기" 를 판단합니다.
• updated_after 를 주면 그 시각 이후 바뀐 것만 돌려주세요(권장).
• 연결 확인은 page=1&page_size=1 로 한 번 부릅니다.

2. 매니페스트#

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

{
  "dataset_id": "ds-inspect-2026w29",
  "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" }
    }
  ]
}

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 를 돌려줘도 됩니다.
• 이어받기(Range)는 아직 쓰지 않습니다. 실패한 파일은 다음 동기화에서 통째로 다시 받습니다.
• 파일 하나는 2 GiB 까지입니다(서버 설정으로 바꿀 수 있음).

오류 응답#

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

플랫폼은 이 본문을 해석하지 않고 앞부분을 사용자에게 보여 줍니다. 원인이 드러나는 한 문장을 담아 주세요.

필드 별칭#

응답 필드 이름은 아래 중 무엇을 써도 됩니다. 앞에 있는 것부터 찾고, 비어 있지 않은 첫 값을 씁니다.

이 표에 없는 이름이 꼭 필요하면 플랫폼 팀에 알려 주세요. 한 줄 추가로 받을 수 있습니다.

지원하는 파일 형식#

CSV · Parquet 는 확장자로 시계열과 표를 가를 수 없으므로, 목록의 modality 를 tabular 로 알려 주거나 데이터셋을 만들 때 모달리티를 직접 고르게 해 주세요.

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