API REST
Une API REST est une API construite dans le style REST (Representational State Transfer) : chaque jeu de données est une ressource avec sa propre URL, la méthode HTTP fixe l’action et le serveur ne conserve aucun état du client entre les requêtes. Roy Fielding a décrit ce style dans sa thèse de doctorat en 2000.
Anatomie d’une requête
Une requête des taux de funding du BTC sur tous les exchanges :
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| Élément | Valeur | Signification |
|---|---|---|
| Méthode | GET | Lire des données |
| URL de base | https://api.genesisarbitrage.com/v1 | Serveur et version de l’API |
| Ressource | /funding/rates | Taux de funding des exchanges |
| Paramètre | coin=BTC | BTC uniquement |
| En-tête | X-API-Key | Clé du client |
La réponse est en JSON : data contient le BTC avec une liste d’exchanges, chacun avec le taux par intervalle de funding (funding_pct) et le taux normalisé sur 8 heures (funding_8h_pct). Sans coin, la même ressource renvoie toutes les coins. Les champs sont décrits dans la section Taux de funding.
Méthodes et état
La méthode indique au serveur ce qu’il doit faire de la ressource. La sémantique des méthodes est fixée par le standard HTTP, RFC 9110 :
GET: récupérer des données ; la méthode est sûre et ne modifie rien sur le serveur ;POST: envoyer des données à traiter ; Binance l’utilise pour passer un ordre (POST /api/v3/order) ;PUT: créer ou remplacer une ressource ;DELETE: supprimer ; Binance l’utilise pour annuler un ordre (DELETE /api/v3/order).
Genesis API ne fournit que des données, donc tous ses endpoints sont des GET.
Sans état (stateless) signifie que chaque requête porte tout ce dont elle a besoin : clé, ressource, filtres. Le serveur ne se souvient pas des appels précédents et GET ne modifie rien ; une requête peut donc être répétée après un délai dépassé ou un 503 : le résultat ne dépend que de la requête elle-même et des données actuelles. Pour éviter de retélécharger des données inchangées, Genesis API envoie un ETag : une requête avec If-None-Match reçoit 304 quand rien n’a changé.
REST et WebSocket
| API REST | WebSocket | |
|---|---|---|
| Interaction | Requête et réponse | Flux de messages dans les deux sens |
| Qui commence | Le client | L’une ou l’autre partie, une fois connectée |
| Adapté à | Instantanés, filtres, historique | Flux de transactions et de carnets d’ordres |
| Dans Genesis API | Tous les endpoints | Non |
Avec REST, on obtient les mises à jour par polling : le programme répète la requête à intervalle régulier. Genesis API actualise sa sortie toutes les meta.freshness_sec secondes, de 60 en Trial à 5 en Max ; interroger plus vite n’apporte rien.
Voir aussi : endpoint, WebSocket, format de réponse, leçon : votre première requête API avec HTTP, en-têtes et JSON.
Questions et réponses
En quoi une API REST diffère-t-elle d’une API en général ?
Une API est un ensemble quelconque de règles par lesquelles des programmes communiquent. Une API REST est un cas particulier sur HTTP : des ressources à des URL, des méthodes standard et des requêtes indépendantes des précédentes.
Dans quel format une API REST répond-elle ?
REST ne fixe pas de format : ce peut être JSON, XML ou un autre type. Genesis API répond en JSON avec compression gzip.