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

Types de données

Les six types du JSON

Vous les avez déjà tous vus en action. Maintenant, donnons-leur un nom, parce que quand vous lisez de la documentation d'API ou que vous parlez à un développeur, ça aide d'utiliser les bons mots.

Le JSON a exactement six types de valeurs. C'est tout. Chaque réponse d'API dans le monde est construite à partir de ces six briques de base.

Les strings (chaînes de caractères)

Du texte, entouré de guillemets doubles. Toujours des guillemets doubles. Les guillemets simples ne fonctionnent pas en JSON.

"alice@acme.com"

C'est le type le plus courant. Noms, emails, identifiants, dates, statuts, URLs : tout ça, ce sont des strings. Si c'est entouré de guillemets, c'est une string.

Un piège à connaître : "true" (avec guillemets) est une string, pas un boolean. Et "42" (avec guillemets) est une string, pas un nombre. Les guillemets font toute la différence.

Les nombres

Juste des nombres. Pas de guillemets, pas de symbole de devise, pas de formatage.

49.99

2000

Vous avez vu dans la leçon 2 que Stripe utilise 2000 pour 20,00 $. C'est un nombre. Si vous voyez "2000" avec des guillemets, c'est une string. Les mêmes chiffres, mais une signification très différente pour le code qui les consomme.

Les nombres peuvent être des entiers (42) ou des décimaux (49.99). Il n'y a pas de distinction en JSON. Ce sont tous simplement des "nombres".

Les booleans

true ou false. Sans guillemets.

true

Pensez à des interrupteurs on/off. Vous les verrez pour :

  • "is_active": true : ce compte est-il actif ?
  • "email_verified": false : l'utilisateur a-t-il confirmé son email ?
  • "auto_renew": true : l'abonnement se renouvelle-t-il automatiquement ?

Quand vous repérez un boolean dans une réponse d'API, posez-vous la question : que signifie "false" pour l'expérience utilisateur ? C'est une question produit.

Null

null. Sans guillemets. Signifie "pas de valeur". Le champ existe, mais il est vide.

null

Ce n'est pas la même chose que "" (string vide), pas la même chose que 0, pas la même chose que false. Ça veut littéralement dire : rien ici.

Vous avez vu "referral_code": null dans la leçon 2. Le champ est là, l'API le reconnaît, mais cet utilisateur n'a pas de code de parrainage.

En tant que PM, null signifie généralement "champ optionnel, non rempli". Quand vous écrivez une spec, ça vaut le coup de se demander : que doit afficher l'interface quand ce champ est null ? Un tiret ? "N/A" ? Rien du tout ?

Les objets

Accolades {}. Une collection de paires clé-valeur.

{
  "name": "Acme Corp",
  "industry": "SaaS",
  "employee_count": 150
}

Vous les connaissez bien maintenant. Les objets regroupent des informations liées entre elles. Ils peuvent être imbriqués (un objet dans un objet) autant que nécessaire.

Les arrays (tableaux)

Crochets []. Une liste ordonnée d'éléments.

["read", "write", "export"]

Les arrays peuvent contenir n'importe quel type : des strings, des nombres, des objets, et même d'autres arrays. Le pattern le plus courant que vous verrez est un array d'objets :

[
  { "id": 1, "name": "Free", "price": 0 },
  { "id": 2, "name": "Pro", "price": 2900 },
  { "id": 3, "name": "Enterprise", "price": null }
]

Remarquez le dernier. "price": null. Le tarif Enterprise est sur-mesure, donc il n'y a pas de prix. Les types se mélangent tout le temps dans les vraies réponses d'API.

Voilà, c'est le JSON

Six types. Deux types de crochets. Vous avez maintenant tout ce qu'il faut pour lire n'importe quelle réponse d'API au monde.

Dans le prochain chapitre, on va voir ce qu'est réellement une API : comment fonctionnent les requêtes et les réponses, et comment votre produit les utilise pour communiquer avec d'autres services.