A API saiu da versão beta no dia dois de julho. Ela foi lançada dentro da revisão 5.4 da plataforma em junho, funcionou como beta por convite desde fevereiro com pouco mais de quatrocentas contas, e não mudou de forma desde abril. Versionada, documentada e coberta pela mesma promessa de disponibilidade que o painel.
Chamar isso de atraso seria generoso. A razão não é misteriosa: uma interface em cima de um sistema de provisionamento que precisava de três minutos e meio para construir um servidor seria uma interface para consultar um spinner. Nós reescrevemos a fila primeiro, em 2025, e a ordem foi deliberada, não sorte.
O que ela faz
| Grupo | O que você pode fazer | Notas |
|---|---|---|
| Instâncias | Criar, redimensionar, reconstruir, tirar snapshot, restaurar, destruir | Redimensionar para cima é ao vivo, para baixo precisa de um reboot |
| Imagens | Listar o catálogo de SO, registrar um ISO personalizado por URL | Instalações de ISO personalizado ainda são manuais e ainda são lentas |
| Rede | Adicionar IPv4, editar DNS reverso, solicitar um IPv6 /48 | Delegadas, nunca proxiadas |
| Filtragem | Ler eventos de ataque, enviar regras de camada 7 no DDoS Pro | A filtragem base não tem nada para configurar |
| Cobrança | Ler saldo, listar faturas, abrir uma fatura de recarga | Sem campos de cartão, porque não há cartões |
| Eventos | Consultar o log de eventos ou registrar um webhook | Assinado com um segredo por conta |
Tudo é JSON sobre HTTPS, e todo objeto que o painel pode mostrar é um objeto que a API pode retornar. Não há um nível de funcionalidade reservado para a interface web, o que é uma promessa que nos custa algo: o painel agora consome os mesmos endpoints públicos que você, então uma API quebrada é um painel quebrado e nós descobrimos imediatamente.
Autenticação
Os tokens são criados no painel, com escopo, e mostrados exatamente uma vez. Sem autenticação por senha, sem cookies de sessão, sem redirecionamento para um provedor de identidade que teríamos que confiar com algo que nos demos ao trabalho de não coletar.
Um token carrega um escopo de leitura, escrita ou cobrança, uma restrição opcional a um único site, uma restrição opcional a uma lista de instâncias, e uma expiração que você define. Sessenta dias é o padrão. Tokens podem ser revogados individualmente e a revogação é efetiva na borda em dois segundos, o que importa mais do que parece quando um servidor de build é reconstruído por alguém que não sabia o que estava nele.
Como uma conta aqui é um endereço de email e um hash de senha, não há objeto de cliente para buscar. A API não tem campo de nome, campo de endereço, campo de empresa e campo de imposto, exatamente pela mesma razão que o formulário de cadastro não tem.
Limites de taxa, idempotência, erros
Seiscentas leituras por minuto e sessenta escritas, contadas por token em vez de por conta, então um script barulhento não pode fazer sua automação passar fome. Limites são retornados em cabeçalhos em todas as respostas, incluindo as bem-sucedidas.
Toda escrita aceita uma chave de idempotência. Repita uma criação com a mesma chave e você recebe a instância original de volta em vez de uma segunda cobrada junto. Esse é o recurso que os testadores beta mais agradeceram, o que diz algo sobre como o resto da indústria lida com um timeout durante o provisionamento.
Erros são um código de máquina documentado, uma frase que um humano pode ler, e um identificador de requisição. Cole o identificador em um ticket e o suporte pode ver a mesma requisição que você viu, sem pedir para reproduzi-la.
O que ela deliberadamente não faz
- Sem fiduciário, jamais. Endpoints de cobrança leem seu saldo e abrem uma fatura de recarga. A liquidação permanece com OxaPay e a blockchain que você escolheu, exatamente como descrito em a página de pagamentos.
- Sem subcontas ou papéis. Solicitado constantemente. Não construído, porque a implementação óbvia significa guardar uma estrutura de quem-trabalha-para-quem, e preferimos emitir tokens com escopo que expiram e deixar você manter seu organograma para você mesmo.
- Sem autoscaling. Instâncias são núcleos dedicados em silício real, não um pool que podemos conjurar. Você pode criar e destruir no seu próprio cronograma; não vamos fingir que há uma abstração elástica por baixo.
- Sem matriz de SDK. Um cliente de referência, e HTTP puro como contrato. Seis bindings de linguagem meio mantidos envelheceriam pior que a documentação.
O que gostaríamos que fosse quebrado
A beta encontrou nove bugs que valiam corrigir, três dos quais foram nossos de uma maneira interessante e seis dos quais foram a documentação mentindo. Se você encontrar um décimo, abusar do limite de taxa é aceitável e esperado durante testes, e o suporte prefere ter o identificador de requisição do que um screenshot.
A referência está em a documentação. O changelog da revisão 5.4 lista os sete endpoints que mudaram de forma entre fevereiro e abril, e essas são as únicas mudanças de quebra que haverá dentro da versão um.