Système et état de santé
Vivacité, disponibilité, métriques, document OpenAPI et capacités du serveur.
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
Vérifier la disponibilité détaillée
GET HEAD /health/ready
Accès: Toute clé ou session valide · Nouvelle tentative: Peut être répétée sans risque (lecture)
Répond ready lorsque la base de données et le stockage répondent, avec le role de ce nœud (api ou reader), l’indication qu’il accepte les écritures à l’instant (writable vaut false sur une passerelle de lecture et tant que le disque conserve sa réserve d’espace libre), l’emplacement de téléchargement partagé d’une passerelle de lecture ainsi que les compteurs agrégés d’admission et de bande passante des téléversements et des téléchargements. Pendant que le serveur termine ses requêtes en cours avant de s’arrêter, ou lorsqu’une dépendance est indisponible, il répond 503 avec Retry-After. La requête ne compte pas dans le budget de requêtes ; pour un répartiteur de charge sans clé, utilisez getReadinessStatus.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
role | string | oui | une valeur parmi api, reader |
sharedDownloads | object | oui | peut être null |
sharedDownloads.slot | integer | oui | au moins 0 |
sharedDownloads.slots | integer | oui | au moins 0 |
sharedDownloads.active | boolean | oui | — |
sharedDownloads.leaseSeconds | integer | oui | au moins 0 |
status | string | oui | une valeur parmi ready |
writable | boolean | oui | — |
replication | object | non | peut être null |
replication.copies | integer | oui | 0–16 |
replication.required | integer | oui | 1–16 |
replication.singleCopyUntil | string (date-time) | oui | peut être null |
replication.node | string | non | jusqu’à 63 caractères |
replication.profile | string | non | une valeur parmi ha-2, ha-3 |
replication.peers | tableau de object | non | jusqu’à 16 éléments |
replication.peers[].name | string | oui | jusqu’à 63 caractères |
replication.peers[].connected | boolean | oui | — |
replication.peers[].disk | string | oui | jusqu’à 24 caractères |
replication.peers[].complete | boolean | oui | — |
replication.peers[].witness | boolean | oui | — |
transfers | object | oui | — |
transfers.uploads | object | oui | — |
transfers.uploads.admission | object | oui | — |
transfers.uploads.bandwidth | object | oui | — |
transfers.uploads.sessions | object | non | — |
transfers.downloads | object | oui | — |
transfers.downloads.admission | object | oui | — |
transfers.downloads.bandwidth | object | oui | — |
transfers.downloads.sessions | object | non | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir les capacités et les limites du serveur
GET HEAD /api/v1/capabilities
Accès: Toute clé ou session valide · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les versions de l’API, le rôle de la passerelle, les indicateurs de fonctionnalités (par exemple selfRegistration ou mirrorFeed) et les limites auxquelles un client s’adapte : le plus grand objet (maxObjectBytes, une chaîne décimale), le plus petit et le plus grand segment multipart, le plus grand nombre de parties et la plus grande taille de page. À lire une fois au démarrage d’un client ; elle ne liste aucune ressource.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
apiVersions | tableau de string | oui | — |
gatewayRole | string | oui | une valeur parmi api, reader |
features | dictionnaire de boolean | oui | — |
limits | object | oui | — |
limits.maxObjectBytes | string | non | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
limits.partBytes | integer | non | Plus petit segment multipart. |
limits.maxPartBytes | integer | non | — |
limits.maxParts | integer | non | — |
limits.maxPageSize | integer | non | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Vérifier la disponibilité pour un répartiteur de charge
GET HEAD /health/status
Accès: Tout le monde, sans clé · Nouvelle tentative: Peut être répétée sans risque (lecture)
Ne nécessite aucune clé et ne renvoie aucun détail : 200 avec {"status":"ready"}, ou 503 avec unavailable ou draining et Retry-After. La vérification des dépendances est partagée et mise en cache pendant une seconde ; des sondes fréquentes ne chargent donc pas la base de données, et la sonde ne compte pas dans le budget de requêtes.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
status | string | oui | une valeur parmi ready, unavailable, draining |
Réponses: 200, 400, 403, 503
Exemple
curl -X GET "$ARKVORY_URL/health/status"Vérifier que le processus est actif
GET HEAD /health/live
Accès: Tout le monde, sans clé · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie 200 avec {"status":"ok"} tant que le processus répond en HTTP. Cette vérification ne contrôle aucune dépendance : utilisez-la pour décider d’un redémarrage, et getReadinessStatus pour décider d’acheminer le trafic.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
status | string | oui | une valeur parmi ok |
Réponses: 200, 400, 403, 503
Exemple
curl -X GET "$ARKVORY_URL/health/live"Obtenir le document OpenAPI
GET HEAD /api/v1/openapi.json
Accès: Toute clé ou session valide · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie le document OpenAPI 3.0 de ce déploiement, avec les extensions x-arkvory-* qui décrivent les règles d’accès, de nouvelle tentative et de passerelle de chaque opération. surface (discovery, identity, catalog, transfers, administration ou operations) ne renvoie que ce domaine ; un paramètre de requête inconnu ou répété donne une erreur 400. Le document est identique pour tous les appelants et n’accorde rien : pour savoir ce que ce justificatif d’identité peut appeler, utilisez listVisibleOperations.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
surface | requête | string | non | une valeur parmi discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions. |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
openapi | string | oui | une valeur parmi 3.0.3 |
info | object | oui | — |
paths | object | oui | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir les métriques Prometheus
GET HEAD /health/metrics
Accès: Toute clé ou session valide · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie les métriques du processus au format texte de Prometheus (text/plain; version=0.0.4) pour un outil de collecte. Les compteurs et les histogrammes appartiennent à ce processus et repartent de zéro après un redémarrage (voir arkvory_process_start_time_seconds) ; les étiquettes se limitent au modèle de route, à la méthode, à la classe de statut et au sens du transfert, et ne nomment jamais un artefact, une clé ni un compte. La collecte ne compte pas dans le budget de requêtes.
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileLister les opérations que ce justificatif peut appeler
GET HEAD /api/v1/operations
Accès: Toute clé ou session valide · Nouvelle tentative: Peut être répétée sans risque (lecture)
Liste les opérations de cette passerelle que le justificatif peut appeler, triées par operationId, chacune avec sa surface, sa règle de nouvelle tentative, les actions requises et les conditions vérifiées seulement au moment de l’appel (comme resource-state ou upload-owner). repository ajoute les opérations de ce dépôt (un dépôt inconnu ou inaccessible au justificatif donne une erreur 404), surface restreint la liste à un domaine ; les pages contiennent limit éléments (1–100, 50 par défaut) ; poursuivez avec after défini sur next. La réponse est indicative : construisez-en des menus, mais chaque requête réelle est de nouveau autorisée, et une passerelle de lecture ne liste aucune méthode de modification.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
repository | requête | string | non | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$ |
surface | requête | string | non | une valeur parmi discovery, identity, catalog, transfers, administration, operations |
after | requête | string | non | correspond à ^[A-Za-z][A-Za-z0-9]{0,95}$ |
limit | requête | integer | non | 1–100; par défaut 50 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
apiVersion | string | oui | une valeur parmi v1 |
documentVersion | string | oui | correspond à ^\d+\.\d+\.\d+$ |
gatewayRole | string | oui | une valeur parmi api, reader |
repository | string | oui | correspond à ^[a-z0-9][a-z0-9_-]{0,63}$; peut être null |
advisory | boolean | oui | une valeur parmi true |
items | tableau de object | oui | jusqu’à 100 éléments |
items[].operationId | string | oui | correspond à ^[A-Za-z][A-Za-z0-9]{0,95}$ |
items[].method | string | oui | une valeur parmi get, head, post, put, patch, delete |
items[].path | string | oui | correspond à ^/; jusqu’à 512 caractères |
items[].summary | string | oui | jusqu’à 1024 caractères |
items[].surface | string | oui | une valeur parmi discovery, identity, catalog, transfers, administration, operations |
items[].visibility | string | oui | une valeur parmi public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator |
items[].retry | string | oui | une valeur parmi read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job |
items[].requiredActions | tableau de string | oui | jusqu’à 33 éléments; aucun élément répété; chaque élément : une valeur parmi 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 | tableau de string | oui | jusqu’à 6 éléments; aucun élément répété; chaque élément : une valeur parmi resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key |
next | string | oui | correspond à ^[A-Za-z][A-Za-z0-9]{0,95}$; peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"