REST API
Uma REST API é uma API construída no estilo REST (Representational State Transfer): cada conjunto de dados é um recurso com sua própria URL, o método HTTP define a ação e o servidor não guarda o estado do cliente entre as requisições. Roy Fielding descreveu esse estilo em sua tese de doutorado, em 2000.
Anatomia de uma requisição
Uma requisição das taxas de funding do BTC em todas as exchanges:
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| Parte | Valor | Significado |
|---|---|---|
| Método | GET | Ler dados |
| URL base | https://api.genesisarbitrage.com/v1 | Servidor e versão da API |
| Recurso | /funding/rates | Taxas de funding das exchanges |
| Parâmetro | coin=BTC | Somente BTC |
| Cabeçalho | X-API-Key | Chave do cliente |
A resposta é JSON: data traz o BTC com uma lista de exchanges, cada uma com a taxa por intervalo de funding (funding_pct) e a taxa normalizada para 8 horas (funding_8h_pct). Sem coin, o mesmo recurso devolve todas as moedas. Os campos estão descritos na seção Taxas de funding.
Métodos e estado
O método diz ao servidor o que fazer com o recurso. A semântica dos métodos é definida pelo padrão HTTP, RFC 9110:
GET: obter dados; o método é seguro e não altera nada no servidor;POST: enviar dados para processamento; a Binance o usa para colocar uma ordem (POST /api/v3/order);PUT: criar ou substituir um recurso;DELETE: remover; a Binance o usa para cancelar uma ordem (DELETE /api/v3/order).
A Genesis API só entrega dados, então todos os seus endpoints são GET.
Stateless (sem estado) significa que cada requisição carrega tudo de que precisa: chave, recurso, filtros. O servidor não lembra chamadas anteriores e o GET não altera nada, então a requisição pode ser repetida após um timeout ou um 503: o resultado depende só da própria requisição e dos dados atuais. Para não baixar de novo dados que não mudaram, a Genesis API envia um ETag: uma requisição com If-None-Match recebe 304 quando nada mudou.
REST e WebSocket
| REST API | WebSocket | |
|---|---|---|
| Interação | Requisição e resposta | Fluxo de mensagens nos dois sentidos |
| Quem inicia | O cliente | Qualquer um dos lados, depois de conectado |
| Indicado para | Retratos dos dados, filtros, histórico | Fluxos de negociações e de order book |
| Na Genesis API | Todos os endpoints | Não |
Com REST, as atualizações vêm por polling: o programa repete a requisição em um intervalo. A Genesis API atualiza sua saída a cada meta.freshness_sec segundos, de 60 no Trial a 5 no Max, então consultar mais rápido não adianta.
Veja também: endpoint, WebSocket, formato de resposta, lição: sua primeira requisição a uma API com HTTP, cabeçalhos e JSON.
Perguntas e respostas
Qual a diferença entre uma REST API e uma API em geral?
API é qualquer conjunto de regras pelo qual programas se comunicam. Uma REST API é um caso específico sobre HTTP: recursos em URLs, métodos padrão e requisições que não dependem das anteriores.
Em que formato uma REST API responde?
O REST não fixa um formato: pode ser JSON, XML ou outro tipo. A Genesis API responde em JSON com compressão gzip.