경로 기반 파일

리포지토리 경로로 지정하는 파일: 리비전, 기록, 복원, 그리고 한 번의 요청으로 다루는 원시 파일.

이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).

작업

접두사로 파일 경로 목록 조회

GET HEAD /api/v1/repositories/{repository}/assets

액세스: 리포지토리 권한: asset.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

prefix(패턴이 아닌 리터럴, 비우면 전체)로 시작하는 모든 파일 경로를 경로순으로 반환하며, 각 항목에 현재 리비전과 아티팩트 ID가 있습니다. 페이징이 없고 일치 항목이 1,000개를 넘으면 더 좁은 접두사를 요구하는 400이 반환되므로, 큰 트리에는 listAssetPage를 사용합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`prefix`	쿼리	string	아니요	—

응답 200

필드	형식	필수	규칙
`items`	object 배열	아니요	—
`items[].path`	string	예	—
`items[].revision`	integer	예	1–2147483647
`items[].artifactId`	string (uuid)	예	—

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

파일 경로를 페이지 단위로 조회

GET HEAD /api/v1/repositories/{repository}/assets/page

액세스: 리포지토리 권한: asset.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

prefix(리터럴, 비우면 전체)로 시작하는 현재 파일 경로를 UTF-8 바이트 순서로 반환하며, 각 항목에 현재 리비전과 아티팩트 ID가 있습니다. 페이지는 limit개 항목(1–100, 기본 50)으로 구성되며 after에 불투명한 next 값을 넣어 이어서 조회합니다. 페이지는 스냅샷이 아니므로 요청 사이에 변경된 경로는 더 새로운 리비전으로 나타나거나 다음 순회까지 누락될 수 있습니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`prefix`	쿼리	string	아니요	1024자 이하; 기본값 ``; Case-sensitive literal prefix; % and _ are ordinary characters.
`after`	쿼리	string	아니요	`^[A-Za-z0-9_-]+$` 패턴과 일치; 1–8192자
`limit`	쿼리	integer	아니요	1–100; 기본값 `50`

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 100개 이하
`items[].path`	string	예	—
`items[].revision`	integer	예	1–2147483647
`items[].artifactId`	string (uuid)	예	—
`next`	string	예	`^[A-Za-z0-9_-]+$` 패턴과 일치; 1–8192자; null일 수 있음; 리포지토리와 접두사에 묶인 불투명 커서. 끝이면 null. 접근 권한을 부여하지 않습니다.

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

파일 경로의 현재 리비전 조회

GET HEAD /api/v1/repositories/{repository}/asset

액세스: 리포지토리 권한: asset.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

path의 현재 revision과 그 경로가 가리키는 아티팩트의 ID를 반환하며, 알 수 없는 경로는 404입니다. 경로는 /로 구분된 세그먼트로 이루어진 1–1024자이며, 빈 세그먼트, .·.. 세그먼트, \, :, 제어 문자를 포함할 수 없습니다. 바이트는 downloadAssetContent로 다운로드하고, 리비전은 setAsset에 expectedRevision으로 전달합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`path`	쿼리	string	예	—

응답 200

필드	형식	필수	규칙
`path`	string	예	—
`revision`	integer	예	1–2147483647
`artifactId`	string (uuid)	예	—

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

파일 경로가 아티팩트를 가리키게 설정

PUT /api/v1/repositories/{repository}/asset

액세스: 리포지토리 권한: asset.write, artifact.read; 파일 키: read, write · 재시도: 예상 리비전으로만 반복(compare-and-swap)

path가 같은 리포지토리의 게시된 아티팩트를 새 리비전으로 가리키게 합니다. expectedRevision은 경로를 만들 때는 0, 교체할 때는 현재 리비전이어야 하며, 그렇지 않으면 409 revision_mismatch입니다. 이전 리비전은 기록에 남고, 그 리비전이 가리키는 아티팩트가 삭제되지 않도록 지켜 줍니다. 바이트 저장과 이름 지정을 한 요청으로 하려면 putRawFile을 사용합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치

요청 본문 (application/json)

필드	형식	필수	규칙
`path`	string	예	—
`artifactId`	string (uuid)	예	—
`expectedRevision`	integer	예	0–2147483646

응답 200

필드	형식	필수	규칙
`path`	string	예	—
`revision`	integer	예	1–2147483647
`artifactId`	string (uuid)	예	—

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'

파일 경로의 리비전 목록

GET HEAD /api/v1/repositories/{repository}/asset/history

액세스: 리포지토리 권한: asset.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

path의 리비전을 최신순으로 페이지당 50개 반환하며, 각 항목에 아티팩트, 행위자, 시각이 있고 복원이면 복사한 sourceRevision도 있습니다(초기 서버 버전이 기록한 리비전은 행위자와 시각이 null입니다). before에 next 값을 넣어 이어서 조회합니다. 알 수 없는 경로는 404입니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`path`	쿼리	string	예	—
`before`	쿼리	integer	아니요	1–2147483647; Only revisions strictly smaller than this value

응답 200

필드	형식	필수	규칙
`items`	object 배열	예	요소 50개 이하
`items[].path`	string	예	—
`items[].revision`	integer	예	1–2147483647
`items[].artifactId`	string (uuid)	예	—
`items[].actor`	string	예	null일 수 있음; 마이그레이션 4 이전에 기록된 항목은 null
`items[].createdAt`	string (date-time)	예	null일 수 있음; 마이그레이션 4 이전에 기록된 항목은 null
`items[].sourceRevision`	integer	예	1–2147483647; null일 수 있음; 복원된 리비전. 일반 교체이면 null
`next`	integer	예	1–2147483647; null일 수 있음; 커서 이전(해당 값 제외). 끝이면 null

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

파일 경로의 특정 리비전 조회

GET HEAD /api/v1/repositories/{repository}/asset/revision

액세스: 리포지토리 권한: asset.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

path의 리비전 revision을 아티팩트 ID, 행위자, 시각, 복원 원본과 함께 반환합니다. 리비전은 절대 바뀌지 않으므로 아티팩트 ID를 캐시할 수 있으며, 다운로드는 downloadArtifact로 합니다. 없는 경로나 리비전은 404입니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`path`	쿼리	string	예	—
`revision`	쿼리	integer	예	1–2147483647

응답 200

필드	형식	필수	규칙
`path`	string	예	—
`revision`	integer	예	1–2147483647
`artifactId`	string (uuid)	예	—
`actor`	string	예	null일 수 있음; 마이그레이션 4 이전에 기록된 항목은 null
`createdAt`	string (date-time)	예	null일 수 있음; 마이그레이션 4 이전에 기록된 항목은 null
`sourceRevision`	integer	예	1–2147483647; null일 수 있음; 복원된 리비전. 일반 교체이면 null

응답: 200, 400, 401, 403, 404, 409, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

파일 경로의 이전 리비전 복원

POST /api/v1/repositories/{repository}/asset/restore

액세스: 리포지토리 권한: asset.restore, asset.read, artifact.read; 파일 키: read, write · 재시도: 예상 리비전으로만 반복(compare-and-swap)

sourceRevision의 아티팩트를 가리키는 path의 새 리비전을 추가하며, 아무것도 복사되지 않고 어떤 리비전도 제거되지 않습니다. expectedRevision은 현재 리비전(1 이상)이어야 하며 그렇지 않으면 409 revision_mismatch입니다. 따라서 이미 성공한 복원을 반복하면 두 번째 복원이 되지 않고 409가 됩니다. 새 리비전에는 sourceRevision이 기록되며, 이 변경은 같은 트랜잭션에서 감사 기록에 남습니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치

요청 본문 (application/json)

필드	형식	필수	규칙
`path`	string	예	—
`sourceRevision`	integer	예	1–2147483647
`expectedRevision`	integer	예	1–2147483646

응답 200

필드	형식	필수	규칙
`path`	string	예	—
`revision`	integer	예	1–2147483647
`artifactId`	string (uuid)	예	—

응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

예제

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'

경로로 파일 다운로드

GET HEAD /api/v1/repositories/{repository}/asset/content

액세스: 리포지토리 권한: content.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

path를 현재 리비전으로 확인하고 해당 아티팩트를 downloadArtifact와 같은 방식으로 스트리밍하며, Range, If-Range, If-None-Match, HEAD를 지원합니다. 경로는 요청마다 새로 확인되므로 반환된 ETag를 If-Range에 지정해 재개합니다. 그 사이 경로가 바뀌었다면 두 버전이 섞인 응답 대신 새 파일 전체를 반환합니다. downloadRawFile은 경로를 URL에 넣는다는 점만 다를 뿐 같은 일을 합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`Range`	헤더	string	아니요	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	헤더	string	아니요	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	헤더	string	아니요	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	헤더	string	아니요	`^[A-Za-z0-9_-]{16,64}$` 패턴과 일치; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time.
`Arkvory-Queue-Ticket`	헤더	string	아니요	80자 이하; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored.
`Arkvory-Download-Class`	헤더	string	아니요	`interactive`, `release`, `bulk`, `background` 중 하나; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied.
`path`	쿼리	string	예	—

응답: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

한 번의 요청으로 경로에 파일 업로드

PUT /api/v1/repositories/{repository}/raw/{assetPath}

액세스: 리포지토리 권한: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; 파일 키: write · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄

스크립트와 CI(curl -T)를 위해, 미디어 형식에 관계없이 요청 본문을 URL에 있는 경로의 새 리비전으로 저장하며, 응답은 경로, 리비전, 아티팩트를 담은 201입니다. X-Checksum-Sha256 및 Content-Length 헤더를 함께 보내면 바이트가 스토리지로 바로 스트리밍되어 검증되고, 보내지 않으면 먼저 임시 저장소에 받아 해시를 계산합니다(지정한 체크섬과 본문이 다르면 422). 현재 리비전과 같은 바이트는 아무것도 추가하지 않고 created: false와 함께 200으로 응답합니다. If-None-Match: *를 보내면 경로가 없을 때만 생성하며(이미 있으면 409 already_exists), 같은 경로에 동시에 쓰는 다른 작성자는 409 revision_mismatch를 받습니다. 매우 큰 파일에는 재개 가능한 업로드 세션을 권장합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`assetPath`	경로	string	예	1–1024자; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`X-Checksum-Sha256`	헤더	string	아니요	`^[a-fA-F0-9]{64}$` 패턴과 일치; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422).
`If-None-Match`	헤더	string	아니요	`` 중 하나; "": store only when the path does not exist yet (409 already_exists).

요청 본문 (application/octet-stream)

응답 200

필드	형식	필수	규칙
`path`	string	예	—
`revision`	integer	예	1 이상
`created`	boolean	예	—
`artifact`	object	예	—
`artifact.id`	string (uuid)	예	—
`artifact.size`	string	예	10진수 숫자로 쓴 정수이며 문자열로 전송
`artifact.sha256`	string	예	SHA-256: 소문자 16진수 64자리

응답: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

예제

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

URL 경로로 파일 다운로드

GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}

액세스: 리포지토리 권한: content.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)

URL에 있는 경로의 현재 리비전을 downloadArtifact와 같은 방식으로 스트리밍하며, Range, If-Range, If-None-Match, HEAD를 지원하고 X-Arkvory-Artifact-Id 헤더로 아티팩트를 알려 줍니다. 경로는 요청마다 새로 확인되므로 반환된 ETag를 If-Range에 지정해 재개하거나 아티팩트를 ID로 다운로드합니다.

매개 변수

이름	위치	형식	필수	규칙
`repository`	경로	string	예	`^[a-z0-9][a-z0-9_-]{0,63}$` 패턴과 일치
`assetPath`	경로	string	예	1–1024자; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`Range`	헤더	string	아니요	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	헤더	string	아니요	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	헤더	string	아니요	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	헤더	string	아니요	`^[A-Za-z0-9_-]{16,64}$` 패턴과 일치; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time.
`Arkvory-Queue-Ticket`	헤더	string	아니요	80자 이하; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored.
`Arkvory-Download-Class`	헤더	string	아니요	`interactive`, `release`, `bulk`, `background` 중 하나; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied.

응답: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

예제

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

경로 기반 파일 ​

작업 ​

접두사로 파일 경로 목록 조회 ​

파일 경로를 페이지 단위로 조회 ​

파일 경로의 현재 리비전 조회 ​

파일 경로가 아티팩트를 가리키게 설정 ​

파일 경로의 리비전 목록 ​

파일 경로의 특정 리비전 조회 ​

파일 경로의 이전 리비전 복원 ​

경로로 파일 다운로드 ​

한 번의 요청으로 경로에 파일 업로드 ​

URL 경로로 파일 다운로드 ​

경로 기반 파일

작업

접두사로 파일 경로 목록 조회

파일 경로를 페이지 단위로 조회

파일 경로의 현재 리비전 조회

파일 경로가 아티팩트를 가리키게 설정

파일 경로의 리비전 목록

파일 경로의 특정 리비전 조회

파일 경로의 이전 리비전 복원

경로로 파일 다운로드

한 번의 요청으로 경로에 파일 업로드

URL 경로로 파일 다운로드