Arquivos por caminho

Arquivos endereçados por um caminho no repositório: versões, histórico, restauração e arquivos brutos (raw) em uma única solicitação.

Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).

Operações

Listar caminhos de arquivo por prefixo

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

Acesso: Permissão no repositório: asset.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna todos os caminhos de arquivo que começam com prefix (literal, não um padrão; vazio para todos), ordenados por caminho, cada um com sua revisão atual e o ID do artefato. Não há paginação: mais de 1000 correspondências geram 400 pedindo um prefixo mais restrito, portanto prefira listAssetPage para árvores grandes.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	consulta	string	não	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	não	—
`items[].path`	string	sim	—
`items[].revision`	integer	sim	1–2147483647
`items[].artifactId`	string (uuid)	sim	—

Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemplo

bash

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

Listar caminhos de arquivo página a página

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

Acesso: Permissão no repositório: asset.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna os caminhos de arquivo atuais que começam com prefix (literal; vazio para todos) em ordem de bytes UTF-8, cada um com sua revisão atual e o ID do artefato. As páginas contêm limit itens (1–100, padrão 50); continue com after definido como o next opaco. As páginas não são um instantâneo: caminhos alterados entre as solicitações podem aparecer com sua revisão mais nova ou deixar de aparecer até a próxima passagem.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	consulta	string	não	até 1024 caracteres; padrão ``; Case-sensitive literal prefix; % and _ are ordinary characters.
`after`	consulta	string	não	corresponde a `^[A-Za-z0-9_-]+$`; 1–8192 caracteres
`limit`	consulta	integer	não	1–100; padrão `50`

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	sim	até 100 itens
`items[].path`	string	sim	—
`items[].revision`	integer	sim	1–2147483647
`items[].artifactId`	string (uuid)	sim	—
`next`	string	sim	corresponde a `^[A-Za-z0-9_-]+$`; 1–8192 caracteres; pode ser null; Cursor opaco vinculado ao repositório e ao prefixo; null no fim. Nunca concede acesso.

Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemplo

bash

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

Obter a revisão atual de um caminho de arquivo

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

Acesso: Permissão no repositório: asset.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna a revision atual de path e o ID do artefato para o qual ele aponta; um caminho desconhecido gera 404. Um caminho tem de 1 a 1024 caracteres em segmentos separados por /, sem segmentos vazios, . ou .., e sem \, : nem caracteres de controle. Baixe os bytes com downloadAssetContent ou passe a revisão para setAsset como expectedRevision.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sim	—

Resposta 200

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`revision`	integer	sim	1–2147483647
`artifactId`	string (uuid)	sim	—

Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemplo

bash

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

Apontar um caminho de arquivo para um artefato

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

Acesso: Permissão no repositório: asset.write, artifact.read; chaves em arquivo: read, write · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Faz path nomear um artefato publicado do mesmo repositório como sua nova revisão; expectedRevision é 0 para criar o caminho e a revisão atual para substituí-lo; caso contrário, 409 revision_mismatch. As revisões anteriores permanecem no histórico e impedem que seus artefatos sejam excluídos. Para armazenar bytes e nomeá-los em uma única solicitação, use putRawFile.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`artifactId`	string (uuid)	sim	—
`expectedRevision`	integer	sim	0–2147483646

Resposta 200

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`revision`	integer	sim	1–2147483647
`artifactId`	string (uuid)	sim	—

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

Exemplo

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}'

Listar as revisões de um caminho de arquivo

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

Acesso: Permissão no repositório: asset.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna as revisões de path, da mais nova para a mais antiga, 50 por página, cada uma com seu artefato, o ator, a hora e, no caso de uma restauração, a sourceRevision que ela copiou (ator e hora são null nas revisões registradas por versões antigas do servidor). Continue com before definido como next. Um caminho desconhecido gera 404.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sim	—
`before`	consulta	integer	não	1–2147483647; Only revisions strictly smaller than this value

Resposta 200

Campo	Tipo	Obrigatório	Regras
`items`	array de object	sim	até 50 itens
`items[].path`	string	sim	—
`items[].revision`	integer	sim	1–2147483647
`items[].artifactId`	string (uuid)	sim	—
`items[].actor`	string	sim	pode ser null; Null para o histórico registrado antes da migração 4
`items[].createdAt`	string (date-time)	sim	pode ser null; Null para o histórico registrado antes da migração 4
`items[].sourceRevision`	integer	sim	1–2147483647; pode ser null; Revisão restaurada; null em uma substituição comum
`next`	integer	sim	1–2147483647; pode ser null; Cursor before exclusivo; null no fim

Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemplo

bash

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

Obter uma revisão de um caminho de arquivo

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

Acesso: Permissão no repositório: asset.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Retorna a revisão revision de path com o ID do artefato, o ator, a hora e a origem da restauração. As revisões nunca mudam, portanto o ID do artefato pode ser mantido em cache; baixe-o com downloadArtifact. Um caminho ou uma revisão inexistente gera 404.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	consulta	string	sim	—
`revision`	consulta	integer	sim	1–2147483647

Resposta 200

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`revision`	integer	sim	1–2147483647
`artifactId`	string (uuid)	sim	—
`actor`	string	sim	pode ser null; Null para o histórico registrado antes da migração 4
`createdAt`	string (date-time)	sim	pode ser null; Null para o histórico registrado antes da migração 4
`sourceRevision`	integer	sim	1–2147483647; pode ser null; Revisão restaurada; null em uma substituição comum

Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Exemplo

bash

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

Restaurar uma revisão anterior de um caminho de arquivo

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

Acesso: Permissão no repositório: asset.restore, asset.read, artifact.read; chaves em arquivo: read, write · Repetição: Repetir somente com a revisão esperada (compare-and-swap)

Adiciona uma nova revisão de path que aponta para o artefato de sourceRevision; nada é copiado e nenhuma revisão é removida. expectedRevision deve ser a revisão atual (pelo menos 1); caso contrário, 409 revision_mismatch — portanto, repetir uma restauração que já teve sucesso gera 409, não uma segunda restauração. A nova revisão registra sourceRevision, e a alteração é auditada na mesma transação.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`

Corpo da solicitação (application/json)

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`sourceRevision`	integer	sim	1–2147483647
`expectedRevision`	integer	sim	1–2147483646

Resposta 200

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`revision`	integer	sim	1–2147483647
`artifactId`	string (uuid)	sim	—

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

Exemplo

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}'

Baixar um arquivo por caminho

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

Acesso: Permissão no repositório: content.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Resolve path para sua revisão atual e transmite esse artefato como downloadArtifact, com Range, If-Range, If-None-Match e HEAD. O caminho é resolvido a cada solicitação; portanto, retome com If-Range definido como o ETag retornado: se o caminho já avançou para outra revisão, a resposta é o novo arquivo inteiro, e não uma mistura dos dois. downloadRawFile faz o mesmo com o caminho na URL.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`Range`	cabeçalho	string	não	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	cabeçalho	string	não	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	cabeçalho	string	não	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	cabeçalho	string	não	corresponde a `^[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`	cabeçalho	string	não	até 80 caracteres; 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`	cabeçalho	string	não	um destes: `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`	consulta	string	sim	—

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

Exemplo

bash

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

Enviar um arquivo para um caminho em uma solicitação

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

Acesso: Permissão no repositório: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; chaves em arquivo: write · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito

Armazena o corpo da solicitação, de qualquer tipo de mídia, como a nova revisão do caminho na URL, para scripts e CI (curl -T); a resposta é 201 com o caminho, a revisão e o artefato. Com X-Checksum-Sha256 e Content-Length, os bytes vão direto para o armazenamento e são verificados; sem eles, são primeiro gravados em área temporária (staging) e têm o hash calculado (422 se o corpo não corresponder a um checksum informado). Os mesmos bytes da revisão atual não adicionam nada e respondem 200 com created: false, If-None-Match: * apenas cria (409 already_exists), e um escritor concorrente do mesmo caminho recebe 409 revision_mismatch. Para arquivos muito grandes, prefira as sessões de upload retomáveis.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	caminho	string	sim	1–1024 caracteres; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`X-Checksum-Sha256`	cabeçalho	string	não	corresponde a `^[a-fA-F0-9]{64}$`; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422).
`If-None-Match`	cabeçalho	string	não	um destes: ``; "": store only when the path does not exist yet (409 already_exists).

Corpo da solicitação (application/octet-stream)

Resposta 200

Campo	Tipo	Obrigatório	Regras
`path`	string	sim	—
`revision`	integer	sim	pelo menos 1
`created`	boolean	sim	—
`artifact`	object	sim	—
`artifact.id`	string (uuid)	sim	—
`artifact.size`	string	sim	um número inteiro em dígitos decimais, enviado como string
`artifact.sha256`	string	sim	SHA-256: 64 dígitos hexadecimais minúsculos

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

Exemplo

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

Baixar um arquivo pelo caminho da URL

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

Acesso: Permissão no repositório: content.read; chaves em arquivo: read · Repetição: Pode ser repetida com segurança (leitura)

Transmite a revisão atual do caminho na URL como downloadArtifact, com Range, If-Range, If-None-Match, HEAD e X-Arkvory-Artifact-Id indicando o artefato. O caminho é resolvido a cada solicitação; portanto, retome com If-Range definido como o ETag retornado ou baixe o artefato pelo ID.

Parâmetros

Nome	Local	Tipo	Obrigatório	Regras
`repository`	caminho	string	sim	corresponde a `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	caminho	string	sim	1–1024 caracteres; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`Range`	cabeçalho	string	não	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	cabeçalho	string	não	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	cabeçalho	string	não	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	cabeçalho	string	não	corresponde a `^[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`	cabeçalho	string	não	até 80 caracteres; 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`	cabeçalho	string	não	um destes: `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.

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

Exemplo

bash

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

Arquivos por caminho ​

Operações ​

Listar caminhos de arquivo por prefixo ​

Listar caminhos de arquivo página a página ​

Obter a revisão atual de um caminho de arquivo ​

Apontar um caminho de arquivo para um artefato ​

Listar as revisões de um caminho de arquivo ​

Obter uma revisão de um caminho de arquivo ​

Restaurar uma revisão anterior de um caminho de arquivo ​

Baixar um arquivo por caminho ​

Enviar um arquivo para um caminho em uma solicitação ​

Baixar um arquivo pelo caminho da URL ​

Arquivos por caminho

Operações

Listar caminhos de arquivo por prefixo

Listar caminhos de arquivo página a página

Obter a revisão atual de um caminho de arquivo

Apontar um caminho de arquivo para um artefato

Listar as revisões de um caminho de arquivo

Obter uma revisão de um caminho de arquivo

Restaurar uma revisão anterior de um caminho de arquivo

Baixar um arquivo por caminho

Enviar um arquivo para um caminho em uma solicitação

Baixar um arquivo pelo caminho da URL