Subidas

Subidas reanudables: crear una sesión de subida, enviar los bytes completos o por partes, completarla y seguir su tarea de finalización.

Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).

Operaciones

Listar las partes recibidas de una subida

GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts

Acceso: Permiso de repositorio: upload.read; claves de archivo: write · Reintento: Se puede repetir (lectura)

Devuelve partBytes, el tamaño de parte fijado para esta subida al crearla (8 MiB, el doble para los archivos que necesitarían más de 10 000 partes; solo la última parte es más corta), y las partes ya almacenadas con su índice, tamaño y SHA-256. Léala antes de reanudar una subida multiparte interrumpida y envíe solo las partes que faltan con putUploadPart. Solo la ve el creador de la subida; para cualquier otra persona es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
partBytes	integer	no	8388608–1073741824; Todas las partes tienen este tamaño salvo la última.
items	array de object	no	—
items[].index	integer	sí	0–9999
items[].size	integer	sí	1–1073741824
items[].sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas

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

Ejemplo

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

Subir una parte

PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}

Acceso: Permiso de repositorio: upload.write; claves de archivo: write · Reintento: Volver a leer la subida y después decidir

Almacena el cuerpo como la parte index (desde 0) de una subida multiparte pendiente; su longitud debe ser exactamente partBytes (de listUploadParts), o el resto en la última parte, y X-Content-SHA256 debe ser el SHA-256 en hexadecimal minúscula de estos bytes; de lo contrario, 422. Las partes pueden llegar en cualquier orden, pero una subida admite una solicitud a la vez (una simultánea recibe 503 busy); enviar de nuevo una parte con el mismo hash es seguro, y un hash distinto para un índice ya almacenado produce un 409 part_mismatch. Cuando todas las partes están almacenadas, llame a completeUpload o a enqueueCompletion.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—
index	ruta	integer	sí	0–9999
X-Content-SHA256	encabezado	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas

Cuerpo de la solicitud (application/octet-stream)

Respuestas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

Ejemplo

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 @file

Completar una subida en segundo plano

POST /api/v1/repositories/{repository}/uploads/{id}/complete-async

Acceso: Permiso de repositorio: upload.complete; claves de archivo: write · Reintento: Volver a leer la tarea y después decidir

Encola la finalización de una subida pendiente para el proceso de trabajo (worker) en lugar de hacerla dentro de la solicitud, y devuelve el trabajo de inmediato con 202; sígalo con getCompletionJob. Llamarla de nuevo para la misma subida devuelve el mismo trabajo, y un trabajo que falló por una causa transitoria se vuelve a encolar. Que un trabajo esté en cola no significa que el artefacto esté publicado: solo lo indica completed. 409 upload_state si la subida ya no está pendiente; 507 queue_full cuando el solicitante tiene 100 trabajos abiertos o el servidor 10 000.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Respuesta 202

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
uploadId	string (uuid)	sí	—
repository	string	sí	—
owner	string	sí	—
status	string	sí	uno de queued, running, completed, failed
generation	integer	sí	0–2147483647
attempts	integer	sí	como mínimo 0
credentialId	string (uuid)	no	ID opcional de la clave administrada que inició la acción; nunca su secreto.
errorCode	string	sí	puede ser null

Respuestas: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Ejemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener un trabajo de finalización

GET HEAD /api/v1/jobs/{id}

Acceso: Permiso de repositorio: job.read; claves de archivo: write · Reintento: Se puede repetir (lectura)

Devuelve el estado de un trabajo de finalización encolado con enqueueCompletion: queued, running, completed (la subida está publicada) o failed con un errorCode, además del número de intentos. El worker lo intenta hasta cinco veces con pausas crecientes; errores como integrity_mismatch fallan de inmediato. Solo lo ve el creador del trabajo; para cualquier otra persona es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
uploadId	string (uuid)	sí	—
repository	string	sí	—
owner	string	sí	—
status	string	sí	uno de queued, running, completed, failed
generation	integer	sí	0–2147483647
attempts	integer	sí	como mínimo 0
credentialId	string (uuid)	no	ID opcional de la clave administrada que inició la acción; nunca su secreto.
errorCode	string	sí	puede ser null

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

Ejemplo

curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Crear una sesión de subida

POST /api/v1/repositories/{repository}/uploads

Acceso: Permiso de repositorio: upload.create; claves de archivo: write · Reintento: Se puede repetir con el mismo Idempotency-Key

Reserva una subida para un archivo descrito por name, size (una cadena decimal), sha256 y, opcionalmente, labels y metadata; devuelve 201 con la sesión (pending, válida durante 7 días) y su Location. Idempotency-Key (1–128 letras, dígitos y _.:-) es obligatorio: la misma clave con la misma descripción devuelve la misma sesión, y con una descripción distinta produce un 409 idempotency_mismatch. El tamaño se reserva de inmediato frente a la cuota del repositorio y la capacidad del servidor (507). Después envíe los bytes completos con putUploadContent, o por partes con putUploadPart y termine con completeUpload.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
Idempotency-Key	encabezado	string	sí	hasta 128 caracteres

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
name	string	sí	1–240 caracteres
size	string	sí	un número entero en dígitos decimales, enviado como cadena
sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
metadata	mapa de string	no	hasta 32 entradas

Respuesta 201

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
repository	string	sí	—
status	string	sí	uno de pending, available, cancelled
createdAt	string (date-time)	sí	—
expiresAt	string (date-time)	sí	—
descriptor	object	sí	—
descriptor.name	string	sí	1–240 caracteres
descriptor.size	string	sí	un número entero en dígitos decimales, enviado como cadena
descriptor.sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
descriptor.labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
descriptor.metadata	mapa de string	no	hasta 32 entradas

Respuestas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

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

Obtener una subida

GET HEAD /api/v1/repositories/{repository}/uploads/{id}

Acceso: Permiso de repositorio: upload.read; claves de archivo: write · Reintento: Se puede repetir (lectura)

Devuelve la sesión con su status (pending, available una vez publicada, cancelled), su caducidad y el descriptor declarado. Si se pierde la respuesta a putUploadContent o a completeUpload, lea esto primero: available significa que el artefacto está publicado con el mismo ID. Solo la ve el creador de la subida; para cualquier otra persona es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
repository	string	sí	—
status	string	sí	uno de pending, available, cancelled
createdAt	string (date-time)	sí	—
expiresAt	string (date-time)	sí	—
descriptor	object	sí	—
descriptor.name	string	sí	1–240 caracteres
descriptor.size	string	sí	un número entero en dígitos decimales, enviado como cadena
descriptor.sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
descriptor.labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
descriptor.metadata	mapa de string	no	hasta 32 entradas

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

Ejemplo

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

Cancelar una subida

DELETE /api/v1/repositories/{repository}/uploads/{id}

Acceso: Permiso de repositorio: upload.cancel; claves de archivo: write · Reintento: Volver a leer la subida y después decidir

Cancela una subida pendiente y la devuelve con el estado cancelled; una subida publicada no se puede cancelar (409 upload_state). Los bytes recibidos se ocultan de inmediato, pero siguen reservados frente a la cuota hasta que la limpieza física en línea del repositorio (setCleanup, desactivada por defecto) los elimina tras su período de gracia.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
repository	string	sí	—
status	string	sí	uno de pending, available, cancelled
createdAt	string (date-time)	sí	—
expiresAt	string (date-time)	sí	—
descriptor	object	sí	—
descriptor.name	string	sí	1–240 caracteres
descriptor.size	string	sí	un número entero en dígitos decimales, enviado como cadena
descriptor.sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
descriptor.labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
descriptor.metadata	mapa de string	no	hasta 32 entradas

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

Ejemplo

curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Subir el archivo completo en una sola solicitud

PUT /api/v1/repositories/{repository}/uploads/{id}/content

Acceso: Permiso de repositorio: upload.write, upload.complete; claves de archivo: write · Reintento: Volver a leer la subida y después decidir

Transmite el cuerpo de la solicitud como el contenido completo de una subida pendiente, lo comprueba con el tamaño y el SHA-256 declarados (422 si no coinciden) y publica el artefacto; la respuesta es la subida con el estado available. Una solicitud interrumpida no deja nada que reanudar: lea la subida con getUpload y envíe el archivo de nuevo desde el byte cero. No sirve para una subida que ya tiene partes (409 upload_state); además, una solicitud debe terminar dentro del plazo de subida del servidor (30 minutos por defecto), así que envíe los archivos grandes por partes.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/octet-stream)

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
repository	string	sí	—
status	string	sí	uno de pending, available, cancelled
createdAt	string (date-time)	sí	—
expiresAt	string (date-time)	sí	—
descriptor	object	sí	—
descriptor.name	string	sí	1–240 caracteres
descriptor.size	string	sí	un número entero en dígitos decimales, enviado como cadena
descriptor.sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
descriptor.labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
descriptor.metadata	mapa de string	no	hasta 32 entradas

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

Ejemplo

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 @file

Completar una subida

POST /api/v1/repositories/{repository}/uploads/{id}/complete

Acceso: Permiso de repositorio: upload.complete; claves de archivo: write · Reintento: Volver a leer la subida y después decidir

Ensambla las partes almacenadas en orden, comprueba el archivo completo con el tamaño y el SHA-256 declarados y publica el artefacto; devuelve la subida con el estado available. Llamarla de nuevo para una subida publicada devuelve el mismo resultado, por lo que también recupera una finalización cuya respuesta se perdió. Una parte ausente produce un 409 parts_incomplete y una discrepancia de contenido un 422; para archivos muy grandes, en los que la solicitud podría agotar el tiempo de espera, use en su lugar enqueueCompletion.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	ruta	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
id	ruta	string (uuid)	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
repository	string	sí	—
status	string	sí	uno de pending, available, cancelled
createdAt	string (date-time)	sí	—
expiresAt	string (date-time)	sí	—
descriptor	object	sí	—
descriptor.name	string	sí	1–240 caracteres
descriptor.size	string	sí	un número entero en dígitos decimales, enviado como cadena
descriptor.sha256	string	sí	SHA-256: 64 dígitos hexadecimales en minúsculas
descriptor.labels	array de string	no	hasta 32 elementos; cada elemento: hasta 64 caracteres
descriptor.metadata	mapa de string	no	hasta 32 entradas

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

Ejemplo

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"