Chapitre 01 — JSON — le langage des API5 min de lecture

Lire de vraies réponses API

Votre première vraie réponse d'API

OK, vous connaissez les bases : les objets {}, les listes [], les paires clé-valeur. Voyons maintenant à quoi ressemble du JSON dans la vraie vie. Le genre de choses que vous allez rencontrer la première fois que vous regarderez une réponse d'API.

Petit avertissement : ça va être plus gros que les exemples de la leçon 1. Pas de panique. Vous avez déjà tout ce qu'il faut.

Un paiement Stripe

Votre app vient de débiter un client. Stripe renvoie ceci :

{
  "id": "pi_3MqKj2LkdIwHu7ix0123abcd",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "customer": "cus_Na6dX7aXxi11N4",
  "created": 1680000000,
  "metadata": {
    "order_id": "order_9876",
    "product": "Annual Pro Plan"
  }
}

Il y a pas mal de choses ici. Ralentissons et décortiquons tout ça.

Les IDs ont l'air bizarres. "pi_3MqKj2...", "cus_Na6dX..." : c'est la façon dont Stripe étiquette les choses. Le préfixe vous dit ce que vous regardez : pi_ = payment intent, cus_ = customer. Vous verrez ce pattern partout. Slack utilise U pour les utilisateurs, C pour les channels, etc. Une fois que vous connaissez le préfixe, vous pouvez immédiatement identifier le type d'objet.

Le montant est 2000, pas 20.00. Ce n'est pas un bug. Stripe stocke les montants en centimes pour éviter les problèmes de décimales. 2000 = 20,00 $. C'est un pattern très courant dans les API de paiement. En tant que PM, c'est exactement le genre de chose que vous voulez savoir avant d'écrire une spec. Sinon votre interface pourrait afficher "2 000 $" au lieu de "20,00 $".

metadata est un objet libre. Votre équipe technique peut y mettre ce qu'elle veut. C'est comme un post-it collé au paiement. Très utile pour relier un paiement à vos propres données (comme order_id).

status est une string, pas un boolean. Ce n'est pas juste "payé" ou "pas payé". Ça peut être "succeeded", "pending", "failed", "canceled", et d'autres encore. Quand vous voyez un champ status dans une API, demandez-vous toujours : quelles sont toutes les valeurs possibles ? C'est une question de spec à laquelle vous pouvez répondre en lisant la documentation.

Un profil utilisateur SaaS

Regardons maintenant quelque chose que vous avez probablement vu des centaines de fois. Un profil utilisateur :

{
  "id": "usr_8a3b2c1d",
  "name": "Alice Martin",
  "email": "alice@acme.com",
  "plan": "pro",
  "is_active": true,
  "monthly_spend": 49.99,
  "permissions": ["read", "write", "export"],
  "company": {
    "name": "Acme Corp",
    "industry": "SaaS",
    "employee_count": 150
  },
  "referral_code": null,
  "created_at": "2024-09-15T09:30:00Z"
}

Zoomons sur quelques éléments.

true et false : sans guillemets. "is_active": true est un boolean. Ça veut dire oui ou non, on ou off. Vous les verrez pour les feature flags, le statut d'abonnement, la vérification d'email... Si vous voyez des guillemets autour ("true"), c'est en fait une string. Une différence subtile mais importante.

null signifie "rien". "referral_code": null. Cet utilisateur n'a pas été parrainé. Le champ existe, mais il n'a pas de valeur. Ce n'est pas "" (du texte vide), ce n'est pas 0, c'est vraiment rien. Quand vous voyez null, pensez : "ce champ est optionnel et n'a pas été rempli."

permissions est une liste. ["read", "write", "export"] : les crochets signifient que c'est un array. Alice a trois permissions. Un autre utilisateur pourrait avoir ["read"] seulement. Les arrays, c'est la façon dont les API représentent "un ou plusieurs éléments".

company est un objet imbriqué. On a vu ça dans la leçon 1. Les infos de l'entreprise d'Alice sont regroupées dans leur propre {}. Pour trouver le secteur d'activité : company.industry → "SaaS".

Cette date bizarre. "2024-09-15T09:30:00Z" est une date au format ISO 8601. Le T sépare la date de l'heure, et le Z signifie UTC. Vous verrez ce format dans quasiment toutes les API. Pas besoin de le mémoriser. Sachez juste que quand vous voyez quelque chose comme 2024-09-15T..., c'est une date.

Des patterns que vous verrez partout

Après avoir lu quelques réponses d'API, vous commencez à remarquer les mêmes patterns encore et encore :

Les IDs préfixés. usr_, pi_, cus_, sub_, evt_... Le préfixe vous indique le type d'objet sans avoir besoin de regarder autre chose.

Les clés en snake_case. is_active, monthly_spend, employee_count. C'est le style de nommage le plus courant dans les API. Certaines utilisent le camelCase (isActive), mais le snake_case domine.

Les dates ISO. "2024-09-15T09:30:00Z". Le format de date universel. Toujours une string, toujours dans cette forme.

Les montants en centimes. 2000 au lieu de 20.00. Courant dans les API de paiement (Stripe, Paddle, etc.) pour éviter les problèmes de virgule flottante.

Null pour les champs optionnels. Si un champ peut être vide, c'est généralement null plutôt que carrément absent.

Les objets metadata. Un {} libre où les équipes peuvent attacher des données personnalisées. Très courant chez Stripe, Segment, et d'autres outils orientés développeurs.

Mini exercice : naviguez dans une grosse réponse

Voici une commande provenant d'une API e-commerce. Prenez une grande inspiration, puis répondez aux questions ci-dessous.

{
  "order": {
    "id": "ord_5f82a",
    "status": "shipped",
    "customer": {
      "name": "Bob Chen",
      "email": "bob@startup.io"
    },
    "items": [
      { "name": "Wireless Mouse", "quantity": 1, "price": 2999 },
      { "name": "USB-C Hub", "quantity": 2, "price": 4500 }
    ],
    "shipping": {
      "method": "express",
      "tracking_number": "1Z999AA10123456784"
    },
    "coupon_code": null
  }
}
  1. Quel est l'email du client ?
  2. Combien d'articles contient la commande ?
  3. Quel est le prix du USB-C Hub (en dollars) ?
  4. Un coupon a-t-il été utilisé ?
  5. Quelle est la méthode de livraison ?

Réponses :

  1. order.customer.email → "bob@startup.io"
  2. order.items contient 2 entrées dans l'array
  3. order.items[1].price → 4500 → 45,00 $ (rappelez-vous : les centimes !)
  4. order.coupon_code → null → pas de coupon
  5. order.shipping.method → "express"

Si c'était faisable pour vous, vous êtes sur la bonne voie. Vous venez de naviguer dans une réponse d'API imbriquée avec des objets, des arrays, des nulls, et des montants en centimes. C'est une compétence du monde réel.