Boas práticas
Padrões recomendados para construir integrações robustas e eficientes com as APIs STEF.
Limitação de taxa
Respeite os cabeçalhos de limitação de taxa devolvidos pela API:
| Cabeçalho | Descrição |
|---|---|
X-RateLimit-Limit | Número máximo de pedidos por janela |
X-RateLimit-Remaining | Pedidos restantes na janela atual |
X-RateLimit-Reset | Timestamp de reinicialização da janela |
Retry-After | Segundos a aguardar (em caso de 429) |
Segurança
Armazenamento de segredos
Utilize variáveis de ambiente ou um gestor de segredos:
# .env
STEF_CLIENT_ID=your_client_id
STEF_CLIENT_SECRET=your_client_secret
# .gitignore
.env
Desempenho
Cache
- Guarde em cache as respostas dos endpoints de leitura que não mudam frequentemente
- Respeite os cabeçalhos
Cache-ControleETag - Utilize pedidos condicionais (
If-None-Match,If-Modified-Since)
Paginação eficiente
- Utilize a paginação por cursor fornecida pela API
- Limite o número de elementos por página (
limit) ao estritamente necessário - Evite carregar todas as páginas de uma só vez
Compressão
Ative a compressão gzip nos seus pedidos:
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept-Encoding: gzip"
Monitorização
- Registe os tempos de resposta e os códigos de retorno
- Configure alertas para erros 4xx e 5xx
- Monitorize o seu consumo de quotas através do painel do portal