Premiers pas

L’API est publique et non authentifiée : ni clé, ni jeton, ni compte. Il n’y a rien à demander avant d’appeler.

curl 'https://api-equides.org/v1/search?q=qabalah'

Trouver un équidé

Deux routes cherchent par nom, et elles ne servent pas le même usage.

Route	Pour	Ordre
/v1/search	alimenter un champ de saisie	par pertinence
/v1/equides?nom=…	filtrer une sélection	par tri demandé, paginé

/v1/search classe et borne son coût pour répondre avant la frappe suivante. /v1/equides filtre et pagine, sans classer.

Les espaces comptent : chaque mot déjà saisi doit figurer dans le nom, seul le dernier vaut pour un début de mot. q=invictus du f ne suggère donc que des noms portant INVICTUS, DU, et un mot commençant par F — c’est ce qui permet à un champ de saisie de se resserrer à mesure que l’on tape.

curl 'https://api-equides.org/v1/search?q=qab&limite=5'

{
  "q": "qab",
  "limite": 5,
  "resultats": [
    {
      "id": "Z4ogLhlkS2CeUdq0bZ0YFw",
      "nom": "QABALAH MERCURY",
      "race": "Trotteur Francais",
      "sexe": "Femelle",
      "annee_naissance": 2026,
      "score": 1
    }
  ]
}

L’identifiant

Le champ id est l’identifiant officiel de l’IFCE : celui qui figure tel quel dans l’URL de la fiche publique sur infochevaux.ifce.fr. Vingt-deux caractères en base64 URL.

Il ouvre les trois routes d’une fiche :

curl 'https://api-equides.org/v1/equides/Z4ogLhlkS2CeUdq0bZ0YFw'
curl 'https://api-equides.org/v1/equides/Z4ogLhlkS2CeUdq0bZ0YFw/pedigree'
curl 'https://api-equides.org/v1/equides/Z4ogLhlkS2CeUdq0bZ0YFw/descendance'

Aucune réponse ne répète un lien qui se déduit d’un identifiant : cela allégeait chaque ligne de liste d’une quarantaine d’octets pour zéro information. Les gabarits d’URL sont publiés une fois pour toutes par le document de découverte.

curl -H 'Accept: application/json' 'https://api-equides.org/'

Conventions

Toutes les routes répondent en GET (et HEAD) et servent de l’application/json; charset=utf-8.

Un paramètre inconnu est refusé, pas ignoré. Une faute de frappe ne peut donc pas se traduire silencieusement par le jeu entier :

curl 'https://api-equides.org/v1/equides?rase=Pur%20Sang'

{
  "type": "https://docs.api-equides.org/guides/erreurs/#erreur-parametre-invalide",
  "title": "Paramètre invalide",
  "status": 400,
  "detail": "paramètre inconnu `rase`",
  "parametre": "rase",
  "indice": "vouliez-vous dire `race` ? paramètres admis : race, robe, sexe, …"
}

Les erreurs suivent la RFC 9457 — voir Erreurs.

Et ensuite

• Filtrer et paginer — combiner les critères, trier, découper
• Généalogie — ascendance et produits directs
• Cache et revalidation — le levier de tenue en charge
• Limites d’usage — ce que borne le service, et pourquoi