A API REST

Todos os caminhos desta página ficam por trás do URL de base indicado abaixo, e cada pedido leva a sua chave num cabeçalho Authorization. Não há outra forma de entrar: sem cookie de sessão, sem basic auth, sem chave na query string.

curl -s https://app.provibr.com/api/v1/me \
  -H "Authorization: Bearer pvk_..."

Uma chave cria-se na sua página de perfil, em Chaves de API. É sua e de uma só conta: não é partilhada com os colegas e deixa de funcionar no momento em que sair dessa conta.

• Salvo indicação em contrário, uma chave expira ao fim de 90 dias. Pode escolher um prazo mais curto, ou nenhum; uma chave sem data de fim é uma chave que ninguém revoga em seu lugar.
• Fazer a rotação significa criar uma chave nova e revogar a antiga, com um intervalo pelo meio em que ambas funcionam. Não há substituição direta da chave existente, porque isso deixaria sem chave a funcionar se algo corresse mal a meio.
• É possível vincular uma chave a uma lista de endereços. Um pedido vindo de qualquer outro sítio é recusado antes de se ler seja o que for, e essa recusa não revela nada sobre a chave a quem o fez.
• Cada membro tem no máximo 25 chaves. Uma chave revogada mantém a sua linha, pelo que se continua a ver mais tarde o que lhe era permitido fazer enquanto esteve em uso.

Uma chave transporta âmbitos: leitura ou escrita, por cada parte do painel. O que pode realmente fazer é a interseção desses âmbitos com as permissões do membro a quem pertence.

As permissões são lidas em direto, em cada pedido. Se algo for retirado a um membro, todas as chaves desse membro ficam imediatamente mais estreitas, sem que ninguém tenha de revogar seja o que for. É também por isso que uma chave sobrevive a uma mudança de função em vez de ser invalidada por ela.

A sua infraestrutura só é alcançável através do agente que está dentro da sua própria rede, e esse agente liga-se para fora. Por isso, um endpoint que altera uma máquina não pode responder com o resultado: responde que a ordem foi aceite e entrega algo que se pode acompanhar.

1. 01Envia-se o pedido e recebe-se uma resposta de aceitação, com um cabeçalho Location que aponta para o comando que foi criado. Esse cabeçalho é absoluto a partir do anfitrião: deve ser resolvido em relação à origem e não ao URL base acima, caso contrário pede-se um caminho que não existe.
2. 02Esse mesmo comando vem também no corpo, mas embrulhado num campo command. A leitura abaixo devolve-o nu, sem esse embrulho: basta desembrulhá-lo uma vez e a primeira leitura costuma ser desnecessária.
3. 03Lê-se o comando até o seu estado ser final: concluído, com falha, expirado ou cancelado. Só pendente não é final, e um estado desconhecido conta igualmente como final, de modo que um valor acrescentado mais tarde nunca deixa a leitura em aberto para sempre.
4. 04Um comando que falhou traz o código de erro do próprio agente, com os seus argumentos: exatamente os mesmos que o painel apresenta.

# 1. the order - answers 202 with a Location header
curl -s -D - -X POST https://app.provibr.com/api/v1/servers/<serverId>/actions/start \
  -H "Authorization: Bearer pvk_..."

# 2. the outcome - repeat until the status is final
curl -s https://app.provibr.com/api/v1/commands/<commandId> \
  -H "Authorization: Bearer pvk_..."

Cada ponto final diz com o que responde: 200 numa leitura, 201 quando algo foi criado, 202 quando o agente ainda tem trabalho a fazer. E todos descrevem o corpo que devolvem, com um nome próprio por recurso, pelo que o código gerado tem um tipo por recurso e não um por ponto final.

As listas respondem com uma página e um cursor; devolve-se esse cursor até vir vazio. Por predefinição, uma página contém 50 linhas e, no máximo, 100.

Todas as respostas que não são um sucesso têm a mesma forma, seja o que for que correu mal e onde quer que tenha corrido mal.

{
  "error": {
    "code": "validation_failed",
    "message": "Name is too long (max 64).",
    "detail": "server.validation.apiKeys.nameTooLong",
    "params": { "max": 64 },
    "requestId": "3f9c1b2a-..."
  }
}

code

A palavra sobre a qual ramificar. Vem de uma lista fechada, pelo que um valor desconhecido significa que se está a falar com uma versão mais recente do que aquela para a qual se construiu.

message

Uma frase em inglês, para quem lê um registo. Nunca ramifique por ela: a formulação pode mudar a qualquer momento.

detail

Uma chave estável, quando existe. É a mesma chave que o painel usa para a sua própria mensagem, o que permite escrever a frase no seu próprio idioma.

params

Os argumentos que pertencem a essa chave: um limite que foi excedido, um nome que já estava ocupado, o host que recusou.

requestId

O identificador deste pedido, presente também num cabeçalho da resposta. Indique-o quando nos perguntar alguma coisa.

São permitidos 120 pedidos por minuto e por chave, e 600 por conta, somando todas as suas chaves. Esse segundo limite existe para que vinte chaves não possam colocar vinte vezes a carga no mesmo host.

Tudo o que cria alguma coisa aceita um cabeçalho idempotency-key à sua escolha. Repita o mesmo pedido com o mesmo valor e receberá de volta o primeiro resultado, em vez de uma segunda máquina, de uma segunda chave ou de um segundo comando.

Também é possível enviar um x-request-id próprio. Volta na resposta e aparece nos nossos registos, que é a forma mais barata de emparelhar uma linha do seu lado com uma linha do nosso.

No encaminhamento desta API não há um único nome de fornecedor. Que sistemas se podem ligar, que campos as respetivas credenciais aceitam e de que são capazes é o que o endpoint de discovery responde, e o corpo que se envia para criar uma integração é construído a partir desse mesmo registo. Um fornecedor que entra em funcionamento aparece em ambos sem que um único endpoint mude.

O contrário também é verdade. Ao pedir a uma máquina algo que o seu fornecedor não sabe fazer (uma consola numa conta de alojamento, um disco num servidor de jogos), obtém-se uma recusa que nomeia a capacidade em falta, antes de qualquer coisa ser enviada para o agente.

Agrupados como a especificação os agrupa. Cada caminho vem depois do URL de base e, ao lado, está o âmbito que o endpoint exige; onde não está nada, basta uma chave válida.

A mesma informação sob a forma de um documento OpenAPI 3.1, gerado a partir do código que serve estes endpoints em vez de escrito ao lado dele. Entregue-o a um gerador de clientes, a um editor ou a um conjunto de testes.

curl -s https://app.provibr.com/api/v1/openapi.json

Dentro desta versão, as alterações são adições: novos endpoints, novos campos opcionais, novos valores numa lista. Leia com tolerância os campos que não conhece e não trate como fatal um código de erro que não conhece.