REST API
Una REST API es una API construida con el estilo REST (Representational State Transfer): cada conjunto de datos es un recurso con su propia URL, el método HTTP fija la acción y el servidor no guarda el estado del cliente entre peticiones. Roy Fielding describió este estilo en su tesis doctoral del año 2000.
Desglose de una petición
Una petición de las tasas de funding de BTC en todos los exchanges:
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| Parte | Valor | Significado |
|---|---|---|
| Método | GET | Leer datos |
| URL base | https://api.genesisarbitrage.com/v1 | Servidor y versión de la API |
| Recurso | /funding/rates | Tasas de funding de los exchanges |
| Parámetro | coin=BTC | Solo BTC |
| Cabecera | X-API-Key | Clave del cliente |
La respuesta es JSON: data contiene BTC con una lista de exchanges, cada uno con la tasa por intervalo de funding (funding_pct) y la tasa normalizada a 8 horas (funding_8h_pct). Sin coin, el mismo recurso devuelve todas las monedas. Los campos se describen en la sección Tasas de funding.
Métodos y estado
El método indica al servidor qué hacer con el recurso. La semántica de los métodos la fija el estándar HTTP, RFC 9110:
GET: obtener datos; el método es seguro y no cambia nada en el servidor;POST: enviar datos para su procesamiento; Binance lo usa para colocar una orden (POST /api/v3/order);PUT: crear o reemplazar un recurso;DELETE: eliminar; Binance lo usa para cancelar una orden (DELETE /api/v3/order).
Genesis API solo entrega datos, así que todos sus endpoints son GET.
Sin estado (stateless) significa que cada petición lleva todo lo que necesita: clave, recurso, filtros. El servidor no recuerda llamadas anteriores y GET no cambia nada, así que una petición puede repetirse tras un tiempo de espera agotado o un 503: el resultado depende solo de la propia petición y de los datos actuales. Para no descargar datos sin cambios, Genesis API envía un ETag: una petición con If-None-Match recibe 304 cuando nada ha cambiado.
REST frente a WebSocket
| REST API | WebSocket | |
|---|---|---|
| Interacción | Petición y respuesta | Flujo de mensajes en ambos sentidos |
| Quién empieza | El cliente | Cualquiera de las partes, una vez conectados |
| Sirve para | Instantáneas, filtros, historial | Flujos de operaciones y de libro de órdenes |
| En Genesis API | Todos los endpoints | No |
Con REST las actualizaciones se obtienen por polling: el programa repite la petición a intervalos. Genesis API actualiza su salida cada meta.freshness_sec segundos, de 60 en Trial a 5 en Max, así que consultar más rápido no aporta nada.
Véase también: endpoint, WebSocket, formato de respuesta, lección: tu primera petición a una API con HTTP, cabeceras y JSON.
Preguntas y respuestas
¿En qué se diferencia una REST API de una API en general?
Una API es cualquier conjunto de reglas con el que los programas se comunican. Una REST API es un caso concreto sobre HTTP: recursos en URL, métodos estándar y peticiones que no dependen de las anteriores.
¿En qué formato responde una REST API?
REST no fija un formato: puede ser JSON, XML u otro tipo. Genesis API responde en JSON con compresión gzip.