Fichiers par chemin
Fichiers adressés par un chemin dans le dépôt : révisions, historique, restauration et fichiers bruts en une seule requête.
Opérations de ce groupe, avec leur règle d’accès, leur règle de nouvelle tentative, leurs paramètres et leurs réponses. Chaque requête porte une clé : Authorization: Bearer <clé> (voir « Authentification »).
Opérations
Lister les chemins de fichiers par préfixe
GET HEAD /api/v1/repositories/{repository}/assets
Accès: Autorisation sur le dépôt : asset.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie tous les chemins de fichiers qui commencent par prefix (littéral, pas un motif ; vide pour tous), triés par chemin, chacun avec sa révision actuelle et l’ID de l’artefact. Il n’y a pas de pagination : plus de 1000 correspondances donnent une erreur 400 qui demande un préfixe plus étroit ; préférez donc listAssetPage pour les grandes arborescences.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | requête | string | non | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | non | — |
items[].path | string | oui | — |
items[].revision | integer | oui | 1–2147483647 |
items[].artifactId | string (uuid) | oui | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Lister les chemins de fichiers page par page
GET HEAD /api/v1/repositories/{repository}/assets/page
Accès: Autorisation sur le dépôt : asset.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les chemins de fichiers actuels qui commencent par prefix (littéral ; vide pour tous) dans l’ordre des octets UTF-8, chacun avec sa révision actuelle et l’ID de l’artefact. Les pages contiennent limit éléments (1–100, 50 par défaut) ; poursuivez avec after défini sur le next opaque. Les pages ne sont pas un instantané : des chemins modifiés entre deux requêtes peuvent apparaître avec leur révision plus récente ou être manqués jusqu’au prochain passage.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | requête | string | non | jusqu’à 1024 caractères; par défaut ``; Case-sensitive literal prefix; % and _ are ordinary characters. |
after | requête | string | non | correspond à ^[A-Za-z0-9_-]+$; 1–8192 caractères |
limit | requête | integer | non | 1–100; par défaut 50 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].path | string | oui | — |
items[].revision | integer | oui | 1–2147483647 |
items[].artifactId | string (uuid) | oui | — |
next | string | oui | correspond à ^[A-Za-z0-9_-]+$; 1–8192 caractères; peut être null; Curseur opaque lié au dépôt et au préfixe ; null à la fin. N’accorde jamais d’accès. |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir la révision actuelle d’un chemin de fichier
GET HEAD /api/v1/repositories/{repository}/asset
Accès: Autorisation sur le dépôt : asset.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie la revision actuelle de path et l’ID de l’artefact vers lequel il pointe ; un chemin inconnu donne 404. Un chemin compte 1–1024 caractères en segments séparés par /, sans segment vide, . ni .., et sans \, : ni caractère de contrôle. Téléchargez les octets avec downloadAssetContent, ou passez la révision à setAsset comme expectedRevision.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | requête | string | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
revision | integer | oui | 1–2147483647 |
artifactId | string (uuid) | oui | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Faire pointer un chemin de fichier vers un artefact
PUT /api/v1/repositories/{repository}/asset
Accès: Autorisation sur le dépôt : asset.write, artifact.read; clés de fichier : read, write · Nouvelle tentative: Répéter uniquement avec la révision attendue (compare-and-swap)
Fait désigner par path un artefact publié du même dépôt comme sa nouvelle révision ; expectedRevision vaut 0 pour créer le chemin et la révision actuelle pour le remplacer, sinon 409 revision_mismatch. Les révisions précédentes restent dans l’historique et empêchent la suppression de leurs artefacts. Pour stocker des octets et les nommer en une seule requête, utilisez putRawFile.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
artifactId | string (uuid) | oui | — |
expectedRevision | integer | oui | 0–2147483646 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
revision | integer | oui | 1–2147483647 |
artifactId | string (uuid) | oui | — |
Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
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}'Lister les révisions d’un chemin de fichier
GET HEAD /api/v1/repositories/{repository}/asset/history
Accès: Autorisation sur le dépôt : asset.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les révisions de path, de la plus récente à la plus ancienne, 50 par page, chacune avec son artefact, l’acteur, l’heure et, pour une restauration, la sourceRevision qu’elle a copiée (l’acteur et l’heure sont null pour les révisions enregistrées par les premières versions du serveur). Poursuivez avec before défini sur next. Un chemin inconnu donne 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | requête | string | oui | — |
before | requête | integer | non | 1–2147483647; Only revisions strictly smaller than this value |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 50 éléments |
items[].path | string | oui | — |
items[].revision | integer | oui | 1–2147483647 |
items[].artifactId | string (uuid) | oui | — |
items[].actor | string | oui | peut être null; null pour l’historique enregistré avant la migration 4 |
items[].createdAt | string (date-time) | oui | peut être null; null pour l’historique enregistré avant la migration 4 |
items[].sourceRevision | integer | oui | 1–2147483647; peut être null; Révision restaurée ; null pour un remplacement ordinaire |
next | integer | oui | 1–2147483647; peut être null; Curseur exclusif « avant » ; null à la fin |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir une révision d’un chemin de fichier
GET HEAD /api/v1/repositories/{repository}/asset/revision
Accès: Autorisation sur le dépôt : asset.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie la révision revision de path avec l’ID de son artefact, l’acteur, l’heure et la source de restauration. Les révisions ne changent jamais : l’ID de l’artefact peut donc être mis en cache ; téléchargez-le avec downloadArtifact. Un chemin ou une révision manquants donnent 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | requête | string | oui | — |
revision | requête | integer | oui | 1–2147483647 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
revision | integer | oui | 1–2147483647 |
artifactId | string (uuid) | oui | — |
actor | string | oui | peut être null; null pour l’historique enregistré avant la migration 4 |
createdAt | string (date-time) | oui | peut être null; null pour l’historique enregistré avant la migration 4 |
sourceRevision | integer | oui | 1–2147483647; peut être null; Révision restaurée ; null pour un remplacement ordinaire |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Restaurer une révision antérieure d’un chemin de fichier
POST /api/v1/repositories/{repository}/asset/restore
Accès: Autorisation sur le dépôt : asset.restore, asset.read, artifact.read; clés de fichier : read, write · Nouvelle tentative: Répéter uniquement avec la révision attendue (compare-and-swap)
Ajoute une nouvelle révision de path qui pointe vers l’artefact de sourceRevision ; rien n’est copié et aucune révision n’est supprimée. expectedRevision doit être la révision actuelle (au moins 1), sinon 409 revision_mismatch : répéter une restauration déjà réussie donne donc un 409, et non une seconde restauration. La nouvelle révision enregistre sourceRevision, et la modification est auditée dans la même transaction.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
sourceRevision | integer | oui | 1–2147483647 |
expectedRevision | integer | oui | 1–2147483646 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
revision | integer | oui | 1–2147483647 |
artifactId | string (uuid) | oui | — |
Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
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}'Télécharger un fichier par chemin
GET HEAD /api/v1/repositories/{repository}/asset/content
Accès: Autorisation sur le dépôt : content.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Résout path vers sa révision actuelle et diffuse en flux cet artefact comme downloadArtifact, avec Range, If-Range, If-None-Match et HEAD. Le chemin est résolu à chaque requête : reprenez donc avec If-Range défini sur l’ETag renvoyé ; si le chemin a évolué entre-temps, la réponse est le nouveau fichier entier et non un fichier mélangé. downloadRawFile fait de même avec le chemin dans l’URL.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
Range | en-tête | string | non | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | en-tête | string | non | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | en-tête | string | non | Matching ETag returns 304, including HEAD. |
Arkvory-Download-Id | en-tête | string | non | correspond à ^[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 | en-tête | string | non | jusqu’à 80 caractères; 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 | en-tête | string | non | une valeur parmi 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 | requête | string | oui | — |
Réponses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileTéléverser un fichier vers un chemin en une seule requête
PUT /api/v1/repositories/{repository}/raw/{assetPath}
Accès: Autorisation sur le dépôt : upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet
Stocke le corps de la requête, de n’importe quel type de média, comme nouvelle révision du chemin donné dans l’URL, pour les scripts et le CI (curl -T) ; la réponse est 201 avec le chemin, la révision et l’artefact. Avec X-Checksum-Sha256 et Content-Length, les octets sont diffusés directement vers le stockage et vérifiés ; sans eux, ils sont d’abord placés en zone temporaire (staging) et leur empreinte est calculée (422 si le corps ne correspond pas à une somme de contrôle donnée). Des octets identiques à ceux de la révision actuelle n’ajoutent rien et répondent 200 avec created: false, If-None-Match: * ne fait que créer (409 already_exists), et un écrivain concurrent sur le même chemin reçoit 409 revision_mismatch. Pour les très gros fichiers, préférez les sessions de téléversement reprenables.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | chemin | string | oui | 1–1024 caractères; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
X-Checksum-Sha256 | en-tête | string | non | correspond à ^[a-fA-F0-9]{64}$; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422). |
If-None-Match | en-tête | string | non | une valeur parmi *; "*": store only when the path does not exist yet (409 already_exists). |
Corps de la requête (application/octet-stream)
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
path | string | oui | — |
revision | integer | oui | au moins 1 |
created | boolean | oui | — |
artifact | object | oui | — |
artifact.id | string (uuid) | oui | — |
artifact.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
artifact.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
Réponses: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileTélécharger un fichier par le chemin de l’URL
GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}
Accès: Autorisation sur le dépôt : content.read; clés de fichier : read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Diffuse en flux la révision actuelle du chemin donné dans l’URL comme downloadArtifact, avec Range, If-Range, If-None-Match, HEAD et X-Arkvory-Artifact-Id qui désigne l’artefact. Le chemin est résolu à chaque requête : reprenez donc avec If-Range défini sur l’ETag renvoyé, ou téléchargez l’artefact par ID.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | chemin | string | oui | 1–1024 caractères; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
Range | en-tête | string | non | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | en-tête | string | non | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | en-tête | string | non | Matching ETag returns 304, including HEAD. |
Arkvory-Download-Id | en-tête | string | non | correspond à ^[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 | en-tête | string | non | jusqu’à 80 caractères; 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 | en-tête | string | non | une valeur parmi 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. |
Réponses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file