A API

Tudo o que o site faz, fá-lo por esta API — não há outra privada. Cinco ferramentas, uma só forma: cria um trabalho, segue-o e leva o resultado. Sem chave vai pelo carril gratuito; com ela, pelos limites altos.

Onde vive

https://bigitools.com

A sua chave

Serve qualquer um dos cabeçalhos, o que for mais fácil para o seu cliente:

Authorization: Bearer ok_…
X-API-Key: ok_…

Uma chave que não reconhece leva um 401, de propósito: NÃO cai em silêncio para o carril gratuito. Se a copiar mal, descobre-o na primeira chamada e não quando lhe bate um limite que não lhe competia.

Um trabalho, do princípio ao fim

1. 1. Crie-o

   curl -X POST $API/api/jobs \
     -H 'Authorization: Bearer ok_…' \
     -H 'Content-Type: application/json' \
     -d '{"tool":"mail-doctor","input":{"domain":"example.com"}}'
   
   { "id": "cm…", "status": "queued", "stream": "/api/jobs/cm…/stream", "key": "n7Qk…" }

   Guarde a chave: é entregue UMA vez e não a podemos reenviar. Ler o trabalho, os seus ficheiros e cancelá-lo precisam dela — envie-a como X-Job-Key, ou como ?key= onde não seja possível um cabeçalho. Guardamos apenas a sua impressão digital, por isso uma chave perdida é um trabalho a que já não chega; de qualquer forma expira com o relatório. Se o trabalho foi criado com a chave de API de uma conta, essa também o abre e pode esquecer esta.

   As ferramentas que precisam de credenciais recebem-nas num objeto secret à parte, nunca dentro de input: a entrada fica com o trabalho e o segredo é cifrado e apagado assim que o trabalho termina.

2. 2. Siga-o

   Consulte GET /api/jobs/:id, ou abra o fluxo e receba os passos à medida que acontecem:

   curl -N "$API/api/jobs/cm…/stream?key=n7Qk…"

   O fluxo são Server-Sent Events e cada evento leva um id. Se cair, volte a ligar com ?desde=<último id> e recebe o que perdeu em vez de começar do zero. Aqui a chave vai no URL e não num cabeçalho, porque um cliente SSE não consegue enviar cabeçalhos — mais uma razão para saber que um URL com a chave lá dentro acaba nos registos de acesso.

3. 3. Leve o resultado

   Chega em result quando o trabalho está done. As ferramentas que produzem ficheiros acrescentam:

   GET /api/jobs/:id/export/:format  o relatório — /api/tools lista os formatos
   GET /api/jobs/:id/files           o que foi produzido, em lista
   GET /api/jobs/:id/files/<path>    um deles
   GET /api/jobs/:id/download.zip    todos de uma vez

   As quatro querem a chave, tal como tudo o resto relativo a esse trabalho.

O resto

GET  /api/health            o serviço está de pé, e a fila anda
GET  /api/tools             o catálogo: limites do nível gratuito e formatos
GET  /api/me                o seu plano e o que já gastou
POST /api/jobs/:id/cancel   parar um que ainda esteja a correr
POST /api/mailtest          um endereço de uso único para onde enviar uma mensagem (devolve também uma chave)
GET  /api/mailtest/:id      se chegou, e que trabalho a avaliou (precisa dessa chave)
POST /api/monitors          vigiar um IP, um certificado, um domínio ou o seu DNS
GET  /api/monitors          o que está a vigiar, e o que mudou
DELETE /api/monitors/:id    deixar de vigiar
GET  /api/ip                o endereço a partir do qual este servidor o vê, com o seu DNS inverso
GET  /api/ip/plain          o mesmo, uma linha, sem JSON para interpretar — para o terminal
GET  /api/is-it-down?url=…  esse site está em baixo, ou é apenas consigo — verificado a partir daqui
GET  /api/speed             o que o teste de velocidade pode gastar e o que resta
GET  /api/speed/down        bytes com que medir; POST /api/speed/up para o outro sentido

Como é um erro

Todo o erro responde em JSON com error: uma frase em inglês, escrita para ser lida de um terminal. Alguns levam também code, um identificador estável pensado para programas, para que um cliente decida sem analisar prosa. Ramifique por code quando existir, e mostre error quando não.

Os códigos que existem hoje:

body-too-large
internal-error
invalid-credentials
invalid-input
job-already-finished
job-expired
job-expired-live
job-no-files
job-not-finished
job-not-found
job-not-yours
job-owner-unknown
key-bad-format
key-not-recognised
mailtest-not-found
monitor-dns-target
monitor-domain-date-ambiguous
monitor-domain-interval
monitor-domain-no-expiry
monitor-domain-no-whois
monitor-domain-registry-list
monitor-domain-silent
monitor-domain-target
monitor-duplicate
monitor-field
monitor-http-no-dns
monitor-http-private
monitor-http-target
monitor-interval
monitor-ip-not-ipv4
monitor-ip-private
monitor-ip-v6
monitor-limit
monitor-no-webhook
monitor-not-found
monitor-tls-is-ip
monitor-tls-target
monitor-webhook-url
monitoring-needs-account
monitoring-not-open
monitoring-paid-plan
monitoring-paid-plan-closed
rate-limited
rate-limited-checks
rate-limited-speed
result-expired
speed-budget-client
speed-budget-server
speed-no-accounting
stream-broken
stream-unavailable
zip-failed

O que significam os códigos

O relatório, no idioma do seu utilizador

Acrescente ?lang= e o que a ferramenta escreve volta traduzido: o que diz cada verificação, o progresso, o registo e o motivo por que uma tarefa falhou. Nove idiomas; inglês se não indicar nada.

GET /api/jobs/:id?lang=de                 o relatório, traduzido
GET /api/jobs/:id/stream?lang=de          progresso e registo, à medida que acontece
GET /api/jobs/:id/export/:format?lang=de  o ficheiro que descarrega, traduzido

lang: de · en · es · fr · it · nl · pl · pt · ro

Só muda o texto. O código de um erro é o mesmo nos nove — é por ele que se decide, e a mensagem é a que se pode mostrar tal como vem. O Accept-Language é ignorado de propósito: é o idioma do navegador, não o da página que o seu utilizador está a ler, e misturar os dois mete frases em espanhol dentro de um relatório em inglês.

As ferramentas, e o que lhe dá o carril gratuito

Os limites são lidos ao vivo de /api/tools, não estão escritos aqui: um catálogo escrito à mão fica desatualizado na primeira ferramenta que se acrescente.

Duas coisas que vale a pena saber

• · A credencial é a chave do trabalho, não o identificador. É entregue uma vez na criação e dela guardamos só uma impressão digital. Quem a tiver lê esse relatório até expirar: trate a chave como o próprio relatório.
• · Os resultados expiram. Descarregue o que precisar; depois vai-se também a entrada, não só a saída.