Sistema y estado

Actividad (liveness), disponibilidad (readiness), métricas, el documento OpenAPI y las capacidades del servidor.

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

Comprobar la preparación detallada

GET HEAD /health/ready

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Responde ready cuando la base de datos y el almacenamiento responden, e indica el role de este nodo (api o reader), si acepta escrituras ahora (writable es falso en una puerta de enlace de lectura y mientras el disco conserva su reserva de espacio libre), la ranura de descarga compartida de una puerta de enlace de lectura y los contadores agregados de admisión y de ancho de banda de las subidas y las descargas. Mientras el servidor termina las solicitudes en curso antes de detenerse o una dependencia no está disponible, responde 503 con Retry-After. No cuenta para el límite de solicitudes; para un balanceador de carga sin clave use getReadinessStatus.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
role	string	sí	uno de api, reader
sharedDownloads	object	sí	puede ser null
sharedDownloads.slot	integer	sí	como mínimo 0
sharedDownloads.slots	integer	sí	como mínimo 0
sharedDownloads.active	boolean	sí	—
sharedDownloads.leaseSeconds	integer	sí	como mínimo 0
status	string	sí	uno de ready
writable	boolean	sí	—
replication	object	no	puede ser null
replication.copies	integer	sí	0–16
replication.required	integer	sí	1–16
replication.singleCopyUntil	string (date-time)	sí	puede ser null
replication.node	string	no	hasta 63 caracteres
replication.profile	string	no	uno de ha-2, ha-3
replication.peers	array de object	no	hasta 16 elementos
replication.peers[].name	string	sí	hasta 63 caracteres
replication.peers[].connected	boolean	sí	—
replication.peers[].disk	string	sí	hasta 24 caracteres
replication.peers[].complete	boolean	sí	—
replication.peers[].witness	boolean	sí	—
transfers	object	sí	—
transfers.uploads	object	sí	—
transfers.uploads.admission	object	sí	—
transfers.uploads.bandwidth	object	sí	—
transfers.uploads.sessions	object	no	—
transfers.downloads	object	sí	—
transfers.downloads.admission	object	sí	—
transfers.downloads.bandwidth	object	sí	—
transfers.downloads.sessions	object	no	—

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

Ejemplo

curl -X GET "$ARKVORY_URL/health/ready" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener las capacidades y los límites del servidor

GET HEAD /api/v1/capabilities

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Devuelve las versiones de la API, el rol de la puerta de enlace, los indicadores de funcionalidades (por ejemplo selfRegistration o mirrorFeed) y los límites a los que se adapta un cliente: el objeto más grande (maxObjectBytes, una cadena decimal), el segmento multiparte más pequeño y el más grande, el mayor número de partes y el mayor tamaño de página. Léalo una vez al iniciar un cliente; no enumera recursos.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
apiVersions	array de string	sí	—
gatewayRole	string	sí	uno de api, reader
features	mapa de boolean	sí	—
limits	object	sí	—
limits.maxObjectBytes	string	no	un número entero en dígitos decimales, enviado como cadena
limits.partBytes	integer	no	Segmento multiparte más pequeño.
limits.maxPartBytes	integer	no	—
limits.maxParts	integer	no	—
limits.maxPageSize	integer	no	—

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

Ejemplo

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

Comprobar la preparación para un balanceador de carga

GET HEAD /health/status

Acceso: Cualquiera, sin clave · Reintento: Se puede repetir (lectura)

No requiere clave y no devuelve detalles: 200 con {"status":"ready"}, o 503 con unavailable o draining y Retry-After. La comprobación de dependencias es compartida y se guarda en caché durante un segundo, de modo que los sondeos frecuentes no cargan la base de datos, y el sondeo no cuenta para el límite de solicitudes.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
status	string	sí	uno de ready, unavailable, draining

Respuestas: 200, 400, 403, 503

Ejemplo

curl -X GET "$ARKVORY_URL/health/status"

Comprobar que el proceso está activo

GET HEAD /health/live

Acceso: Cualquiera, sin clave · Reintento: Se puede repetir (lectura)

Devuelve 200 con {"status":"ok"} mientras el proceso responde por HTTP. No comprueba ninguna dependencia: úselo para decidir un reinicio y getReadinessStatus para decidir si recibe tráfico.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
status	string	sí	uno de ok

Respuestas: 200, 400, 403, 503

Ejemplo

curl -X GET "$ARKVORY_URL/health/live"

Obtener el documento OpenAPI

GET HEAD /api/v1/openapi.json

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Devuelve el documento OpenAPI 3.0 de este despliegue, con las extensiones x-arkvory-* que describen las reglas de acceso, de reintento y de puerta de enlace de cada operación. surface (discovery, identity, catalog, transfers, administration u operations) devuelve solo esa área; un parámetro de consulta desconocido o repetido produce un 400. El documento es el mismo para todos los solicitantes y no concede nada: para saber qué puede invocar esta credencial, use listVisibleOperations.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
surface	consulta	string	no	uno de discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
openapi	string	sí	uno de 3.0.3
info	object	sí	—
paths	object	sí	—

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

Ejemplo

curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener las métricas de Prometheus

GET HEAD /health/metrics

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Devuelve las métricas del proceso en el formato de texto de Prometheus (text/plain; version=0.0.4) para un recolector. Los contadores y los histogramas pertenecen a este proceso y empiezan de cero tras un reinicio (véase arkvory_process_start_time_seconds); las etiquetas se limitan a la plantilla de ruta, el método, la clase de estado y la dirección de la transferencia, y nunca nombran un artefacto, una clave ni una cuenta. La lectura de las métricas no cuenta para el límite de solicitudes.

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

Ejemplo

curl -X GET "$ARKVORY_URL/health/metrics" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Listar las operaciones que esta credencial puede invocar

GET HEAD /api/v1/operations

Acceso: Cualquier clave o sesión válida · Reintento: Se puede repetir (lectura)

Enumera las operaciones de esta puerta de enlace que la credencial puede invocar, ordenadas por operationId, cada una con su superficie, su regla de reintento, las acciones requeridas y las conditions que solo se comprueban al invocar (como resource-state o upload-owner). repository añade las operaciones de ese repositorio (un repositorio desconocido o ajeno produce un 404) y surface limita la lista a un área; las páginas contienen limit elementos (1–100, 50 por defecto); continúe pasando next como after. La respuesta es orientativa: construya menús a partir de ella, pero cada solicitud real se autoriza de nuevo, y una puerta de enlace de lectura no enumera métodos que modifiquen datos.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
repository	consulta	string	no	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$
surface	consulta	string	no	uno de discovery, identity, catalog, transfers, administration, operations
after	consulta	string	no	coincide con ^[A-Za-z][A-Za-z0-9]{0,95}$
limit	consulta	integer	no	1–100; predeterminado: 50

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
apiVersion	string	sí	uno de v1
documentVersion	string	sí	coincide con ^\d+\.\d+\.\d+$
gatewayRole	string	sí	uno de api, reader
repository	string	sí	coincide con ^[a-z0-9][a-z0-9_-]{0,63}$; puede ser null
advisory	boolean	sí	uno de true
items	array de object	sí	hasta 100 elementos
items[].operationId	string	sí	coincide con ^[A-Za-z][A-Za-z0-9]{0,95}$
items[].method	string	sí	uno de get, head, post, put, patch, delete
items[].path	string	sí	coincide con ^/; hasta 512 caracteres
items[].summary	string	sí	hasta 1024 caracteres
items[].surface	string	sí	uno de discovery, identity, catalog, transfers, administration, operations
items[].visibility	string	sí	uno de public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator
items[].retry	string	sí	uno de read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job
items[].requiredActions	array de string	sí	hasta 33 elementos; sin elementos repetidos; cada elemento: uno de repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage
items[].conditions	array de string	sí	hasta 6 elementos; sin elementos repetidos; cada elemento: uno de resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key
next	string	sí	coincide con ^[A-Za-z][A-Za-z0-9]{0,95}$; puede ser null

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

Ejemplo

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