Sistema e integridade
Liveness, readiness, métricas, o documento OpenAPI e as capacidades do servidor.
Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).
Operações
Verificar a prontidão detalhada
GET HEAD /health/ready
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Responde ready quando o banco de dados e o armazenamento respondem, com o role deste nó (api ou reader), se ele aceita gravações agora (writable é false em um gateway de leitura e enquanto o disco mantém sua reserva de espaço livre), o slot de download compartilhado de um gateway de leitura e os contadores agregados de admissão e de largura de banda de upload e download. Enquanto o servidor drena as conexões ou uma dependência está indisponível, responde 503 com Retry-After. Não conta no orçamento de solicitações; para um balanceador de carga sem chave, use getReadinessStatus.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
role | string | sim | um destes: api, reader |
sharedDownloads | object | sim | pode ser null |
sharedDownloads.slot | integer | sim | pelo menos 0 |
sharedDownloads.slots | integer | sim | pelo menos 0 |
sharedDownloads.active | boolean | sim | — |
sharedDownloads.leaseSeconds | integer | sim | pelo menos 0 |
status | string | sim | um destes: ready |
writable | boolean | sim | — |
replication | object | não | pode ser null |
replication.copies | integer | sim | 0–16 |
replication.required | integer | sim | 1–16 |
replication.singleCopyUntil | string (date-time) | sim | pode ser null |
replication.node | string | não | até 63 caracteres |
replication.profile | string | não | um destes: ha-2, ha-3 |
replication.peers | array de object | não | até 16 itens |
replication.peers[].name | string | sim | até 63 caracteres |
replication.peers[].connected | boolean | sim | — |
replication.peers[].disk | string | sim | até 24 caracteres |
replication.peers[].complete | boolean | sim | — |
replication.peers[].witness | boolean | sim | — |
transfers | object | sim | — |
transfers.uploads | object | sim | — |
transfers.uploads.admission | object | sim | — |
transfers.uploads.bandwidth | object | sim | — |
transfers.uploads.sessions | object | não | — |
transfers.downloads | object | sim | — |
transfers.downloads.admission | object | sim | — |
transfers.downloads.bandwidth | object | sim | — |
transfers.downloads.sessions | object | não | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obter as capacidades e os limites do servidor
GET HEAD /api/v1/capabilities
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Retorna as versões da API, o papel do gateway, as flags de recurso (por exemplo selfRegistration ou mirrorFeed) e os limites aos quais um cliente se adapta: o maior objeto (maxObjectBytes, uma string decimal), o menor e o maior segmento multipart, o maior número de partes e o maior tamanho de página. Leia-o uma vez quando um cliente iniciar; ele não lista nenhum recurso.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
apiVersions | array de string | sim | — |
gatewayRole | string | sim | um destes: api, reader |
features | mapa de boolean | sim | — |
limits | object | sim | — |
limits.maxObjectBytes | string | não | um número inteiro em dígitos decimais, enviado como string |
limits.partBytes | integer | não | Menor segmento multipart. |
limits.maxPartBytes | integer | não | — |
limits.maxParts | integer | não | — |
limits.maxPageSize | integer | não | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Verificar a prontidão para um balanceador de carga
GET HEAD /health/status
Acesso: Qualquer pessoa, sem chave · Repetição: Pode ser repetida com segurança (leitura)
Não exige chave e não retorna detalhes: 200 com {"status":"ready"} ou 503 com unavailable ou draining e Retry-After. A verificação das dependências é compartilhada e mantida em cache por um segundo, de modo que sondagens frequentes não sobrecarregam o banco de dados, e a sondagem não conta no orçamento de solicitações.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
status | string | sim | um destes: ready, unavailable, draining |
Respostas: 200, 400, 403, 503
Exemplo
curl -X GET "$ARKVORY_URL/health/status"Verificar se o processo está ativo
GET HEAD /health/live
Acesso: Qualquer pessoa, sem chave · Repetição: Pode ser repetida com segurança (leitura)
Retorna 200 com {"status":"ok"} enquanto o processo responde a HTTP. Não verifica nenhuma dependência; use-o para decidir sobre uma reinicialização e getReadinessStatus para decidir sobre o tráfego.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
status | string | sim | um destes: ok |
Respostas: 200, 400, 403, 503
Exemplo
curl -X GET "$ARKVORY_URL/health/live"Obter o documento OpenAPI
GET HEAD /api/v1/openapi.json
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Retorna o documento OpenAPI 3.0 desta implantação, com as extensões x-arkvory-* que descrevem as regras de acesso, de nova tentativa e de gateway de cada operação. surface (discovery, identity, catalog, transfers, administration ou operations) retorna apenas essa área; um parâmetro de consulta desconhecido ou repetido gera 400. O documento é o mesmo para todos os chamadores e não concede nada: para saber o que esta credencial pode chamar, use listVisibleOperations.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
surface | consulta | string | não | um destes: discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions. |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
openapi | string | sim | um destes: 3.0.3 |
info | object | sim | — |
paths | object | sim | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obter as métricas do Prometheus
GET HEAD /health/metrics
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Retorna as métricas do processo no formato de texto do Prometheus (text/plain; version=0.0.4) para um coletor (scraper). Contadores e histogramas pertencem a este processo e recomeçam do zero após uma reinicialização (veja arkvory_process_start_time_seconds); os rótulos se limitam ao modelo de rota, ao método, à classe de status e à direção da transferência e nunca nomeiam um artefato, uma chave ou uma conta. A coleta não conta no orçamento de solicitações.
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileListar as operações que esta credencial pode chamar
GET HEAD /api/v1/operations
Acesso: Qualquer chave ou sessão válida · Repetição: Pode ser repetida com segurança (leitura)
Lista as operações deste gateway que a credencial pode chamar, ordenadas por operationId, cada uma com sua superfície, regra de nova tentativa, ações exigidas e as conditions verificadas somente no momento da chamada (como resource-state ou upload-owner). repository adiciona as operações desse repositório (um repositório desconhecido ou alheio gera 404), surface restringe a lista a uma área; as páginas contêm limit itens (1–100, padrão 50); continue com after definido como next. A resposta é apenas informativa: crie menus a partir dela, mas cada solicitação real é autorizada novamente, e um gateway de leitura não lista métodos que alteram dados.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | consulta | string | não | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
surface | consulta | string | não | um destes: discovery, identity, catalog, transfers, administration, operations |
after | consulta | string | não | corresponde a ^[A-Za-z][A-Za-z0-9]{0,95}$ |
limit | consulta | integer | não | 1–100; padrão 50 |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
apiVersion | string | sim | um destes: v1 |
documentVersion | string | sim | corresponde a ^\d+\.\d+\.\d+$ |
gatewayRole | string | sim | um destes: api, reader |
repository | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$; pode ser null |
advisory | boolean | sim | um destes: true |
items | array de object | sim | até 100 itens |
items[].operationId | string | sim | corresponde a ^[A-Za-z][A-Za-z0-9]{0,95}$ |
items[].method | string | sim | um destes: get, head, post, put, patch, delete |
items[].path | string | sim | corresponde a ^/; até 512 caracteres |
items[].summary | string | sim | até 1024 caracteres |
items[].surface | string | sim | um destes: discovery, identity, catalog, transfers, administration, operations |
items[].visibility | string | sim | um destes: public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator |
items[].retry | string | sim | um destes: read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job |
items[].requiredActions | array de string | sim | até 33 itens; sem itens repetidos; cada item: um destes: 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 | sim | até 6 itens; sem itens repetidos; cada item: um destes: resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key |
next | string | sim | corresponde a ^[A-Za-z][A-Za-z0-9]{0,95}$; pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"