Primeiros pedidos
A forma da API, os grupos de endpoints por área, e o que esperar de uma resposta de erro. O suficiente para o primeiro script.
A forma
- Base:
https://api.fortfox.pt - Versão:
/v1 - Corpo: JSON, com
Content-Type: application/json - Autenticação:
Authorization: Bearer …— ver Autenticação e tokens
O primeiro pedido
curl -H "Authorization: Bearer ffpat_..." \
https://api.fortfox.pt/v1/sites
Devolve os sites a que a credencial tem acesso. Se um token estiver limitado a sites, a lista já vem filtrada — a restrição não é uma verificação no fim, é o que a leitura faz.
Os dois grupos
/v1/me/… — a minha conta
O que é da conta ou da pessoa, e não de um site:
| Área | Para que serve |
|---|---|
/v1/me/api-tokens | gerir tokens (só com sessão, não com token) |
/v1/me/webhooks | subscrições de webhooks e as entregas recentes |
/v1/me/tickets | pedidos de suporte |
/v1/me/notifications | a inbox de acontecimentos |
/v1/sites/… — um site
Tudo o que diz respeito a um site em concreto, com o id no caminho:
| Caminho | Área |
|---|---|
/v1/sites/{id} | o site: ler, actualizar, apagar |
/v1/sites/{id}/origins | origens e verificações de saúde |
/v1/sites/{id}/domains | domínios próprios e verificação |
/v1/sites/{id}/cache-rules | regras de cache |
/v1/sites/{id}/waf/… | configuração da firewall e regras |
/v1/sites/{id}/rate-limit | limite de pedidos |
/v1/sites/{id}/analytics/… | tráfego, cache, ameaças, top IPs |
/v1/sites/{id}/dns/… | zona DNS, quando alojada por nós |
Nem todos exigem o mesmo: as leituras precisam de uma permissão de ver, as escritas de uma de gerir. A especificação diz-o por endpoint.
Erros
Um erro traz um código estável e, quando ajuda, uma mensagem:
{
"error_code": "VALIDATION_ERROR",
"message": "o assunto precisa de pelo menos 3 caracteres"
}
Programa contra o error_code, e não contra a mensagem. O código é contrato; a mensagem é texto para pessoas e pode mudar.
| Estado | O que costuma querer dizer |
|---|---|
400 | o corpo do pedido está mal — a mensagem diz qual o campo |
401 | credencial ausente, expirada ou revogada |
403 | a credencial é válida e não chega para isto |
404 | não existe, ou não é teu — não distinguimos os dois |
409 | conflito: já existe algo igual |
422 | o pedido é coerente e a regra de negócio recusa |
429 | demasiados pedidos — ver Limites de pedidos |
5xx | nosso. Vale a pena tentar outra vez com recuo. |
O 404 que também é um 403
Um recurso de outra conta responde 404, e não 403. É deliberado: a diferença entre «não existe» e «existe e não é teu» é informação, e quem anda a sondar ids aprende com ela.
A especificação completa
A plataforma publica o OpenAPI, e é a fonte a usar para gerar clientes ou validar contratos. A documentação interactiva vive no endpoint de documentação da API.
Se um endpoint aqui e a especificação discordarem, a especificação está mais próxima do código — este guia é uma introdução, não o contrato.
Escrever um script que não se parte
- Guarda o
error_code, não a mensagem. - Trata o
429com recuo, e respeita o que a resposta indicar. - Não presumas ordem numa lista sem parâmetro de ordenação.
- Não presumas campos. Acrescentamos campos às respostas sem aviso; isso não é uma alteração de contrato. Retirar seria.
- Um
idé opaco. Não deduzas nada da forma dele.