Cohérence de l’API

Schémas cohérents sur l’ensemble des endpoints de X API v2

X API v2 est conçue avec des schémas cohérents sur l’ensemble de ses endpoints. Une fois que vous avez compris le fonctionnement d’un endpoint, vous retrouverez les mêmes schémas partout.

---

​

Modèles cohérents

​

Structure d’URL

Tous les endpoints de la v2 suivent un schéma prévisible :

/version/resource/{id}?parameters
/version/resource/verb?parameters

Exemples :

/2/tweets/1234567890                    # Get a specific post
/2/tweets/search/recent                 # Search recent posts
/2/users/by/username/xdevelopers        # Obtenir un utilisateur par nom d'utilisateur
/2/users/1234/followers                 # Get user's followers

​

Structure de la réponse

Toutes les réponses ont la même structure de niveau supérieur :

{
  "data": { ... },       // Objet(s) principal(aux)
  "includes": { ... },   // Objets étendus
  "meta": { ... },       // Pagination, décomptes
  "errors": [ ... ]      // Erreurs partielles (le cas échéant)
}

​

Format des ID

Tous les identifiants sont renvoyés sous forme de chaînes de caractères afin de garantir la compatibilité entre les langages de programmation :

{
  "id": "1234567890123456789",
  "author_id": "2244994945"
}

---

​

Champs et expansions

Les mêmes paramètres fields et expansions fonctionnent de manière cohérente :

Objet	Paramètre fields	Fonctionne sur
Publication	tweet.fields	Tous les endpoints renvoyant des publications
User	user.fields	Tous les endpoints renvoyant des utilisateurs
Media	media.fields	Tous les endpoints avec des expansions media
Poll	poll.fields	Tous les endpoints avec des expansions poll
Place	place.fields	Tous les endpoints avec des expansions place

---

​

Schémas d’objet

Le même type d’objet possède les mêmes champs, quel que soit l’endpoint qui le renvoie :

• Une Publication issue de l’endpoint search a les mêmes champs qu’une Publication issue de l’endpoint lookup
• Un Utilisateur issu de l’endpoint followers a les mêmes champs qu’un Utilisateur issu de l’endpoint search
• Les objets étendus correspondent à leurs équivalents indépendants

---

​

Authentification

Tous les endpoints utilisent les mêmes méthodes d’authentification :

Méthode	Format de l’en-tête
Jeton Bearer	Authorization: Bearer {token}
OAuth 1.0a	Authorization: OAuth {parameters}
OAuth 2.0	Authorization: Bearer {user_token}

---

​

Gestion des erreurs

Les erreurs utilisent un format cohérent :

{
  "title": "Invalid Request",
  "detail": "The query parameter is missing",
  "type": "https://api.x.com/2/problems/invalid-request"
}

Voir tous les types d’erreurs →

---

​

Pagination

Tous les endpoints paginés utilisent le même système de jetons :

Paramètre	Description
max_results	Résultats par page
pagination_token	Jeton provenant de next_token ou previous_token

En savoir plus sur la pagination →

---

​

Conventions de nommage

• Orthographe américaine (favorites plutôt que favourites)
• Snake_case pour les noms de champs (author_id, created_at)
• Terminologie cohérente (retweet_count, et non repost_count dans les champs)

---

​

Valeurs vides

Les champs sans valeur sont omis plutôt que renvoyés comme null :

// User without a bio
{
  "id": "1234",
  "name": "Example User",
  "username": "example"
  // "description" est omis, et non null
}

---

​

Cohérence des entités

L’objet entities ne contient que les entités extraites du texte :

• urls
• hashtags
• mentions
• cashtags

Les médias et les sondages se trouvent dans attachments, pas dans entities.

---

​

Ce que cela signifie pour vous

Apprendre une fois, utiliser partout

Les schémas que vous apprenez sur un endpoint s’appliquent à tous les autres.

Réponses prévisibles

Les mêmes types d’objet présentent les mêmes structures dans toute l’API.

Code simplifié

Créez des fonctions réutilisables pour les schémas récurrents.

Débogage facilité

Des formats d’erreur cohérents facilitent le dépannage.

---

​

Signaler des incohérences

Vous avez trouvé une incohérence ? Faites-le nous savoir :

• Forum des développeurs
• Retour des développeurs