Conventions

Enveloppe de réponse

Toutes les réponses réussies sont enveloppées :

{
  "data": {},
  "meta": { "request_id": "req_abc123" }
}

• data contient la ressource (objet) ou la collection (tableau).
• meta.request_id identifie l’appel — à fournir au support.

L’enveloppe est imposée et stable : de nouveaux champs meta pourront être ajoutés sans casser les clients existants.

Pagination par curseur

Les collections se paginent par curseur (pas d’offset) :

curl "https://api.asap.cool/v1/contacts?limit=50&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer asap_pk_live_..."

La réponse expose le curseur suivant dans meta :

{
  "data": [],
  "meta": {
    "request_id": "req_abc123",
    "next_cursor": "eyJpZCI6IjE3MyJ9",
    "has_more": true
  }
}

Bouclez tant que has_more vaut true, en passant next_cursor à la requête suivante. Le curseur est opaque : ne tentez pas d’en décoder le contenu, il peut changer.

Versioning

• La version est dans l’URL (/v1, /v2) — jamais dans un header.
• Aucun changement cassant à l’intérieur d’une version : /v1 reste stable jusqu’à la sortie de /v2.
• À la sortie de /v2, /v1 est maintenue 12 mois et les réponses portent les headers Deprecation: true et Sunset: <date>.

Voir aussi Erreurs pour les codes et formats d’erreur.