Référence de l'API

La référence interactive

api.taoswap.org/docs est la référence complète de l’API publique. Elle est tirée du schéma OpenAPI de l’API : elle correspond donc à ce que le serveur exécute. Pour chaque opération, elle affiche :

• ses paramètres, avec leurs valeurs par défaut et les vérifications qu’ils doivent passer ;
• la structure de sa réponse, et les réponses d’erreur qu’elle déclare ;
• sa limite de débit, en une phrase et dans un champ x-ratelimit, à côté de la réponse 429 et de son en-tête Retry-After ;
• pour une route en voie de suppression, une marque de dépréciation, sa date de fin dans un champ x-sunset, et son remplacement.

Try it out envoie une vraie requête depuis votre navigateur, qui compte dans votre limite de débit comme n’importe quelle autre.

La référence couvre l’API publique. Les routes que seules les propres applications de Taoswap utilisent en sont exclues.

Le schéma

api.taoswap.org/schema sert la même description sous forme de document OpenAPI 3.0, en YAML par défaut et en JSON avec ?format=json :

curl -o taoswap-openapi.yaml 'https://api.taoswap.org/schema/'
curl -o taoswap-openapi.json 'https://api.taoswap.org/schema/?format=json'

Son info.version est une date. Elle change quand une route ou un champ est annoncé au retrait ou retiré, pas quand un champ est ajouté. Pour suivre les retraits, voir Dépréciations.

Générer un client typé

N’importe quel générateur OpenAPI 3.0 lit le schéma. En TypeScript, openapi-typescript le transforme en types, et openapi-fetch appelle l’API avec eux :

npx openapi-typescript https://api.taoswap.org/schema/ -o taoswap-api.d.ts
npm install openapi-fetch

import createClient from "openapi-fetch";
import type { paths } from "./taoswap-api";

const api = createClient<paths>({ baseUrl: "https://api.taoswap.org" });

const { data, error, response } = await api.GET("/trades/", {
  params: { query: { netuid: 64, page_size: 1 } },
});
if (!data) throw new Error(`HTTP ${response.status}: ${error?.code ?? "no JSON body"}`);
console.log(data.results[0].tao_rao, data.pagination.next_before);

La vérification !data attrape aussi les erreurs du proxy devant l’API, qui arrivent en HTML sans corps JSON.

Pour d’autres langages, OpenAPI Generator en couvre beaucoup, et openapi-python-client écrit un client Python.

Quel que soit le générateur :

• Réglez l’URL de base sur https://api.taoswap.org.
• Acceptez les champs que vous ne connaissez pas. De nouveaux champs apparaissent sans préavis, et un client qui les rejette casse.
• Lisez l’unité de chaque montant dans sa description. Un type généré dit entier ou nombre, jamais rao ou TAO : voir Unités.
• Lisez la description de chaque paramètre de chemin : selon la route, c’est le netuid d’un subnet, la hotkey d’un validateur, un bloc, ou la clé {block}-{index} d’un extrinsic.
• Attendez-vous à l’objet de pagination de la liste que vous appelez, puisque les listes se paginent de plusieurs façons : voir Pagination.