Téléversements
Téléversements avec reprise : créer une session de téléversement, envoyer les octets en une fois ou par parties, la terminer et suivre sa tâche de finalisation.
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 parties reçues d’un téléversement
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
Accès: Autorisation sur le dépôt : upload.read; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie partBytes, la taille de partie fixée pour ce téléversement à sa création (8 MiB, doublée pour les fichiers qui exigeraient plus de 10 000 parties ; seule la dernière partie est plus courte), ainsi que les parties déjà stockées avec leur index, leur taille et leur SHA-256. Lisez cette réponse avant de reprendre un téléversement en plusieurs parties interrompu et n’envoyez que les parties manquantes avec putUploadPart. Seul le créateur du téléversement la voit ; pour tout autre appelant, c’est une erreur 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
partBytes | integer | non | 8388608–1073741824; Chaque partie a cette taille, sauf la dernière. |
items | tableau de object | non | — |
items[].index | integer | oui | 0–9999 |
items[].size | integer | oui | 1–1073741824 |
items[].sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Téléverser une partie
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
Accès: Autorisation sur le dépôt : upload.write; clés de fichier : write · Nouvelle tentative: Relire le téléversement, puis décider
Stocke le corps comme partie index (à partir de 0) d’un téléversement en plusieurs parties en attente ; sa longueur doit être exactement partBytes (obtenu par listUploadParts), ou le reste pour la dernière partie, et X-Content-SHA256 doit être le SHA-256 hexadécimal en minuscules de ces octets, sinon 422. Les parties peuvent arriver dans n’importe quel ordre, mais un téléversement ne traite qu’une requête à la fois (une requête concurrente reçoit 503 busy) ; renvoyer une partie avec la même empreinte est sans risque, une empreinte différente pour un index déjà stocké donne 409 part_mismatch. Lorsque toutes les parties sont stockées, appelez completeUpload ou enqueueCompletion.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
index | chemin | integer | oui | 0–9999 |
X-Content-SHA256 | en-tête | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
Corps de la requête (application/octet-stream)
Réponses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "X-Content-SHA256: $X_CONTENT_SHA256" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileFinaliser un téléversement en arrière-plan
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
Accès: Autorisation sur le dépôt : upload.complete; clés de fichier : write · Nouvelle tentative: Relire la tâche, puis décider
Met en file la finalisation d’un téléversement en attente pour le processus de traitement (worker) au lieu de l’exécuter dans la requête, et renvoie aussitôt la tâche avec 202 ; suivez-la avec getCompletionJob. Un nouvel appel pour le même téléversement renvoie la même tâche, et une tâche qui a échoué pour une cause transitoire est remise en file. Une tâche en file ne signifie pas que l’artefact est publié : seul completed le signifie. 409 upload_state si le téléversement n’est plus en attente ; 507 queue_full lorsque l’appelant a 100 tâches ouvertes ou le serveur 10 000.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 202
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
uploadId | string (uuid) | oui | — |
repository | string | oui | — |
owner | string | oui | — |
status | string | oui | une valeur parmi queued, running, completed, failed |
generation | integer | oui | 0–2147483647 |
attempts | integer | oui | au moins 0 |
credentialId | string (uuid) | non | ID facultatif de la clé gérée à l’origine de l’opération ; jamais son secret. |
errorCode | string | oui | peut être null |
Réponses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir une tâche de finalisation
GET HEAD /api/v1/jobs/{id}
Accès: Autorisation sur le dépôt : job.read; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie l’état d’une tâche de finalisation mise en file avec enqueueCompletion : queued, running, completed (le téléversement est publié) ou failed avec un errorCode, ainsi que le nombre de tentatives. Le processus de traitement essaie jusqu’à cinq fois avec des pauses croissantes ; les erreurs telles que integrity_mismatch font échouer la tâche immédiatement. Seul le créateur de la tâche la voit ; pour tout autre appelant, c’est une erreur 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
uploadId | string (uuid) | oui | — |
repository | string | oui | — |
owner | string | oui | — |
status | string | oui | une valeur parmi queued, running, completed, failed |
generation | integer | oui | 0–2147483647 |
attempts | integer | oui | au moins 0 |
credentialId | string (uuid) | non | ID facultatif de la clé gérée à l’origine de l’opération ; jamais son secret. |
errorCode | string | oui | peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Créer une session de téléversement
POST /api/v1/repositories/{repository}/uploads
Accès: Autorisation sur le dépôt : upload.create; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque avec la même Idempotency-Key
Réserve un téléversement pour un fichier décrit par name, size (une chaîne décimale), sha256 et, en option, labels et metadata ; renvoie 201 avec la session (pending, valable 7 jours) et son Location. Idempotency-Key (1–128 lettres, chiffres et _.:-) est obligatoire : la même clé avec la même description renvoie la même session, avec une description différente c’est une erreur 409 idempotency_mismatch. La taille est aussitôt réservée sur le quota du dépôt et sur la capacité du serveur (507). Envoyez ensuite les octets d’un seul bloc avec putUploadContent, ou en parties avec putUploadPart, et terminez par completeUpload.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
Idempotency-Key | en-tête | string | oui | jusqu’à 128 caractères |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
name | string | oui | 1–240 caractères |
size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponse 201
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
repository | string | oui | — |
status | string | oui | une valeur parmi pending, available, cancelled |
createdAt | string (date-time) | oui | — |
expiresAt | string (date-time) | oui | — |
descriptor | object | oui | — |
descriptor.name | string | oui | 1–240 caractères |
descriptor.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
descriptor.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
descriptor.labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
descriptor.metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponses: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'Obtenir un téléversement
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
Accès: Autorisation sur le dépôt : upload.read; clés de fichier : write · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie la session avec son status (pending, available une fois publié, cancelled), son expiration et le descripteur déclaré. Si la réponse à putUploadContent ou à completeUpload s’est perdue, lisez d’abord cette réponse : available signifie que l’artefact est publié sous le même ID. Seul le créateur du téléversement la voit ; pour tout autre appelant, c’est une erreur 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
repository | string | oui | — |
status | string | oui | une valeur parmi pending, available, cancelled |
createdAt | string (date-time) | oui | — |
expiresAt | string (date-time) | oui | — |
descriptor | object | oui | — |
descriptor.name | string | oui | 1–240 caractères |
descriptor.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
descriptor.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
descriptor.labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
descriptor.metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Annuler un téléversement
DELETE /api/v1/repositories/{repository}/uploads/{id}
Accès: Autorisation sur le dépôt : upload.cancel; clés de fichier : write · Nouvelle tentative: Relire le téléversement, puis décider
Annule un téléversement en attente et le renvoie avec le statut cancelled ; un téléversement publié ne peut pas être annulé (409 upload_state). Les octets reçus sont masqués aussitôt mais restent réservés sur le quota jusqu’à ce que le nettoyage physique en ligne du dépôt (setCleanup, désactivé par défaut) les supprime après son délai de grâce.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
repository | string | oui | — |
status | string | oui | une valeur parmi pending, available, cancelled |
createdAt | string (date-time) | oui | — |
expiresAt | string (date-time) | oui | — |
descriptor | object | oui | — |
descriptor.name | string | oui | 1–240 caractères |
descriptor.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
descriptor.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
descriptor.labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
descriptor.metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Téléverser tout le fichier en une seule requête
PUT /api/v1/repositories/{repository}/uploads/{id}/content
Accès: Autorisation sur le dépôt : upload.write, upload.complete; clés de fichier : write · Nouvelle tentative: Relire le téléversement, puis décider
Diffuse en flux le corps de la requête comme contenu complet d’un téléversement en attente, le compare à la taille et au SHA-256 déclarés (422 en cas de divergence) et publie l’artefact ; la réponse est le téléversement avec le statut available. Une requête interrompue ne laisse rien à reprendre : lisez le téléversement avec getUpload, puis renvoyez le fichier depuis l’octet zéro. Impossible pour un téléversement qui a déjà des parties (409 upload_state) ; la requête doit en outre se terminer dans le délai de téléversement du serveur (30 minutes par défaut) : envoyez donc les gros fichiers en parties.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Corps de la requête (application/octet-stream)
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
repository | string | oui | — |
status | string | oui | une valeur parmi pending, available, cancelled |
createdAt | string (date-time) | oui | — |
expiresAt | string (date-time) | oui | — |
descriptor | object | oui | — |
descriptor.name | string | oui | 1–240 caractères |
descriptor.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
descriptor.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
descriptor.labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
descriptor.metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileFinaliser un téléversement
POST /api/v1/repositories/{repository}/uploads/{id}/complete
Accès: Autorisation sur le dépôt : upload.complete; clés de fichier : write · Nouvelle tentative: Relire le téléversement, puis décider
Assemble dans l’ordre les parties stockées, vérifie le fichier entier par rapport à la taille et au SHA-256 déclarés et publie l’artefact ; renvoie le téléversement avec le statut available. Un nouvel appel pour un téléversement publié renvoie le même résultat : il permet donc aussi de récupérer une finalisation dont la réponse s’est perdue. Une partie manquante donne 409 parts_incomplete, un contenu divergent 422 ; pour les fichiers très volumineux, où la requête risque d’expirer, utilisez plutôt enqueueCompletion.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | chemin | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | chemin | string (uuid) | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
repository | string | oui | — |
status | string | oui | une valeur parmi pending, available, cancelled |
createdAt | string (date-time) | oui | — |
expiresAt | string (date-time) | oui | — |
descriptor | object | oui | — |
descriptor.name | string | oui | 1–240 caractères |
descriptor.size | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
descriptor.sha256 | string | oui | SHA-256 : 64 chiffres hexadécimaux en minuscules |
descriptor.labels | tableau de string | non | jusqu’à 32 éléments; chaque élément : jusqu’à 64 caractères |
descriptor.metadata | dictionnaire de string | non | jusqu’à 32 entrées |
Réponses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"