REST é um estilo de arquitetura descrito por Roy Fielding em 2000. Na prática, chamar uma API REST é fazer requisições HTTP, como as do navegador, trocando dados em vez de páginas.
Os elementos de uma API REST
| Elemento | O que é | Na API da xFlow |
|---|---|---|
| Recurso | A coisa que a API expõe | Cobrança, saque, saldo, webhook. |
| Endereço | Onde o recurso fica | /api/v1/charges/{id} |
| Método | O que fazer com ele | GET consulta, POST cria, PATCH altera, DELETE remove. |
| Corpo | Os dados enviados ou recebidos | JSON em UTF-8. |
| Status | O resultado | 201 criado, 404 não encontrado. |
Outra marca do REST é não guardar sessão no servidor: cada chamada se autentica sozinha. Na xFlow, toda requisição leva o header Authorization com a chave de API.
Na API da xFlow
A documentação descreve a API da xFlow como uma API REST, com JSON e webhooks assinados. Alguns detalhes de desenho:
- Versão no endereço. Tudo fica sob
https://app.xflowpayments.com/api/v1. - Valores em centavos. R$ 19,90 vira
1990, sempre inteiro. - Datas em ISO 8601, em UTC.
- Listas paginadas por cursor.
GET /api/v1/chargesdevolvedataehas_more. Para a página seguinte, enviestarting_aftercom o id do último item. Olimitvai de 1 a 100. - Rastreio. Toda resposta traz um
request_id, no corpo e no headerx-request-id. Ele localiza a chamada em Integrações > Logs da API.
Exemplo
bash
# primeira página das cobranças pagas
curl "https://app.xflowpayments.com/api/v1/charges?status=paid&limit=50" \
-u "pk_live_...:sk_live_..."
# página seguinte, a partir do último id recebido
curl "https://app.xflowpayments.com/api/v1/charges?status=paid&limit=50&starting_after=clx..." \
-u "pk_live_...:sk_live_..."Repita enquanto has_more for true. A resposta 200 traz um payload JSON com a lista. O significado de cada código de resposta está em status HTTP, e o caminho da primeira integração está na área de desenvolvedores.
Termos relacionados
- Status HTTP: como a API diz o resultado de cada chamada.
- Payload: o conteúdo que vai e volta no corpo.
- Rate limit: quantas chamadas a API aceita por conta.
- Webhook: quando é a API que chama o seu sistema.