Protobuf vs JSON pour les API : vitesse, taille et compatibilité

Ce que sont Protobuf et JSON (et pourquoi ça compte)

Quand votre API envoie ou reçoit des données, elle a besoin d'un format de données—une façon standardisée de représenter l'information dans le corps des requêtes et des réponses. Ce format est ensuite sérialisé (transformé en octets) pour le transport sur le réseau, puis désérialisé pour redevenir des objets utilisables côté client et serveur.

Deux choix courants sont JSON et Protocol Buffers (Protobuf). Ils peuvent représenter les mêmes données métier (utilisateurs, commandes, timestamps, listes d'éléments), mais ils font des compromis différents sur la performance, la taille des paquets et le flux de travail développeur.

JSON : texte lisible par l'humain

JSON (JavaScript Object Notation) est un format basé sur du texte construit à partir de structures simples comme des objets et des tableaux. Il est populaire pour les API REST car il est facile à lire, simple à logger et à inspecter avec des outils comme curl et les DevTools du navigateur.

Une grande raison de sa ubiquité : la plupart des langages le supportent très bien, et on peut visualiser une réponse et la comprendre immédiatement.

Protobuf : binaire compact avec schéma

Protobuf est un format de sérialisation binaire créé par Google. Plutôt que d'envoyer du texte, il envoie une représentation binaire compacte définie par un schéma (un fichier .proto). Le schéma décrit les champs, leurs types et leurs numéros de balises.

Parce qu'il est binaire et piloté par un schéma, Protobuf produit généralement des paquets plus petits et peut être plus rapide à analyser—ce qui compte quand vous avez un volume élevé de requêtes, des réseaux mobiles ou des services sensibles à la latence (fréquent avec gRPC, mais pas limité à gRPC).

Même données, compromis différents

Il est important de séparer ce que vous envoyez de comment c'est encodé. Un “utilisateur” avec un id, un nom et un email peut être modélisé en JSON comme en Protobuf. La différence réside dans le coût que vous payez en :

• Taille de la charge utile (texte vs binaire compact)
• Temps CPU pour sérialiser/désérialiser
• Débogage et observabilité (logs lisibles vs outillage binaire)
• Compatibilité et évolution (conventions JSON informelles vs schémas imposés)

Il n’y a pas de réponse universelle. Pour beaucoup d'API publiques, JSON reste le choix par défaut car il est accessible et flexible. Pour la communication interne service-à-service, les systèmes sensibles à la performance ou les contrats stricts, Protobuf peut mieux convenir. L'objectif de ce guide est de vous aider à choisir selon les contraintes—pas l'idéologie.

Comment les données d'une API sont sérialisées et envoyées

Quand une API renvoie des données, elle ne peut pas envoyer des “objets” directement sur le réseau. Il faut d'abord les transformer en flux d'octets. Cette conversion est la sérialisation—pensez-y comme à emballer les données pour l'expédition. De l'autre côté, le client réalise l'opération inverse (désérialisation), déballant les octets en structures de données utilisables.

Un trajet rapide du serveur au client

Un flux typique de requête/réponse ressemble à ceci :

1. Le serveur construit une réponse dans ses types en mémoire (objets/struct/classes).
2. Le sérialiseur encode cette réponse en une charge (texte JSON ou binaire Protobuf).
3. La charge est envoyée sur HTTP/1.1, HTTP/2 ou HTTP/3 sous forme d'octets.
4. Le client reçoit les octets, puis les décode en ses propres types en mémoire.

C'est l'étape d'« encodage » qui fait la différence. L'encodage JSON produit du texte lisible comme {"id":123,"name":"Ava"}. L'encodage Protobuf produit des octets binaires compacts qui n'ont pas de sens pour un humain sans outillage.

Pourquoi le format change la performance et le flux de travail

Parce que chaque réponse doit être empaquetée et dépiautée, le format influence :

• La bande passante (taille des paquets) : des paquets plus petits réduisent les coûts de transfert, utile sur mobile et pour les APIs à fort trafic.
• La latence : moins de données à transmettre peut signifier des réponses plus rapides, et un encodage/décodage plus rapide réduit le temps CPU.
• Le flux de travail développeur : JSON s'inspecte facilement dans DevTools et les logs ; Protobuf nécessite souvent des types générés et des outils spécifiques pour décoder.

Le style d'API oriente souvent la décision

Votre style d'API pousse souvent vers l'une ou l'autre option :

• APIs REST en JSON utilisent généralement JSON car il est largement supporté, simple à tester avec curl et facile à logger.
• gRPC est conçu autour de Protobuf par défaut. Il utilise HTTP/2 et la génération de code, ce qui s'accorde naturellement avec des messages Protobuf fortement typés.

Vous pouvez utiliser JSON avec gRPC (via transcoding) ou Protobuf sur HTTP classique, mais l'ergonomie par défaut de votre stack—frameworks, gateways, bibliothèques clients et habitudes de debugging—décidera souvent de ce qui est le plus simple au quotidien.

Taille des paquets et vitesse : ce que vous gagnez ou perdez en général

Quand on compare protobuf vs json, on commence souvent par deux métriques : la taille des paquets et le temps d'encodage/décodage. Le résumé : JSON est du texte et tend à être verbeux ; Protobuf est binaire et tend à être compact.

Taille des paquets : binaire compact vs texte lisible

JSON répète les noms de champs et utilise des représentations textuelles pour les nombres, booléens et la structure, donc il envoie souvent plus d'octets. Protobuf remplace les noms par des balises numériques et emballe les valeurs efficacement, ce qui conduit généralement à des paquets plus petits—notamment pour les objets volumineux, les champs répétés et les structures profondément imbriquées.

Cela dit, la compression peut réduire l'écart. Avec gzip ou brotli, les clés répétées de JSON se compressent très bien, donc les différences taille JSON vs Protobuf peuvent fondre en production. Protobuf peut aussi être compressé, mais le gain relatif est souvent moindre.

Coût CPU : parser du texte vs décoder du binaire

Les parseurs JSON doivent tokeniser et valider le texte, convertir des chaînes en nombres, et gérer des cas limites (échappements, espaces, unicode). Le décodage Protobuf est plus direct : lire la balise → lire la valeur typée. Dans beaucoup de services, Protobuf réduit le temps CPU et la création de garbage, améliorant la latence aux queues sous charge.

Impact réseau : mobile et liaisons à haute latence

Sur les réseaux mobiles ou les liaisons à haute latence, moins d'octets signifie généralement des transferts plus rapides et moins de temps radio (ce qui aide aussi la batterie). Mais si vos réponses sont déjà petites, le coût d'initialisation, TLS et le traitement serveur peuvent dominer—rendant le choix du format moins visible.

Comment benchmarker dans votre propre système

Mesurez avec vos charges réelles :

• Choisissez des requêtes/réponses représentatives (petites, typiques, pires cas).
• Comparez : taille brute, taille compressée (gzip/brotli), temps d'encodage/décodage et latence bout en bout.
• Lancez des tests à des niveaux de concurrence réalistes et enregistrez p50/p95/p99.

Cela transforme le débat en données exploitables pour votre API.

Expérience développeur : lisibilité, débogage et logging

L'expérience développeur est le domaine où JSON gagne souvent par défaut. Vous pouvez inspecter une réponse JSON presque partout : dans DevTools, la sortie curl, Postman, des proxies inverses et des logs en clair. Quand quelque chose casse, « qu'avons-nous vraiment envoyé ? » est souvent à portée d'un copier/coller.

Protobuf est différent : compact et strict, mais pas lisible. Si vous loggez des octets Protobuf bruts, vous verrez des blobs base64 ou du binaire illisible. Pour comprendre la charge, vous avez besoin du bon schéma .proto et d'un décodeur (par ex. protoc, des outils spécifiques au langage ou les types générés de votre service).

Flux de débogage en pratique

Avec JSON, reproduire un problème est simple : récupérez une charge loggée, redigez les secrets, rejouez-la avec curl et vous êtes proche d'un cas de test minimal.

Avec Protobuf, on déboguera typiquement en :

• capturant la charge binaire (souvent encodée en base64),
• la décodant avec la bonne version du schéma,
• la réencodant pour rejouer la requête.

Cette étape supplémentaire est gérable—à condition que l'équipe ait un workflow reproductible.

Astuces pour faciliter le débogage avec Protobuf (et JSON)

Le logging structuré aide les deux formats. Loggez les IDs de requête, les noms de méthode, les identifiants utilisateur/compte, et quelques champs clés plutôt que tout le corps.

Pour Protobuf en particulier :

• Loggez une vue décodée et redigée (par ex. représentation JSON) en parallèle de la charge binaire quand c'est sûr.
• Stockez la version du schéma ou le type de message dans les logs pour éviter les confusions « quel .proto a-t-on utilisé ? »
• Ajoutez un petit script interne (ou une cible Make) qui peut « décoder ce payload base64 avec le bon schéma » pour l'astreinte.

Pour JSON, pensez à logger du JSON canonisé (ordre stable des clés) pour faciliter les diffs et les timelines d'incident.

Schéma et sécurité de type : flexibilité vs garde-fous

Les APIs ne déplacent pas que des données—elles déplacent du sens. La plus grande différence entre JSON et Protobuf est la clarté et l'application de ce sens.

JSON : forme flexible, interprétations flexibles

JSON est « sans schéma » par défaut : vous pouvez envoyer n'importe quel objet avec n'importe quel champ, et beaucoup de clients l'accepteront tant que la forme semble raisonnable.

Cette flexibilité est pratique au début, mais elle peut cacher des erreurs. Pièges courants :

• Champs incohérents : userId dans une réponse, user_id dans une autre, ou champs absents selon le chemin.
• Données envoyées en chaîne : nombres, booléens ou dates envoyés comme chaînes "42", "true", "2025-12-23"—faciles à produire, faciles à mal interpréter.
• Nulls ambigus : null peut signifier « inconnu », « non défini » ou « volontairement vide », et les clients peuvent le traiter différemment.

Vous pouvez ajouter un JSON Schema ou un OpenAPI, mais JSON lui-même n'oblige pas les consommateurs à s'y conformer.

Protobuf : un contrat explicite via .proto

Protobuf exige un schéma défini dans un fichier .proto. Un schéma est un contrat partagé qui précise :

• quels champs existent,
• quels sont leurs types (string, integer, enum, message, etc.),
• et quel numéro de champ identifie chaque champ sur le fil.

Ce contrat aide à prévenir des changements accidentels—par exemple convertir un entier en chaîne—car le code généré attend des types spécifiques.

Détails de la sécurité de type qui comptent

Avec Protobuf, les nombres restent des nombres, les enums sont bornés aux valeurs connues, et les timestamps sont souvent modélisés avec des types bien connus (plutôt que des formats string ad hoc). « Non défini » est aussi plus clair : en proto3, l'absence est distincte des valeurs par défaut lorsque vous utilisez optional ou des wrapper types.

Si votre API dépend de types précis et d'un parsing prévisible entre équipes/langages, Protobuf offre des garde-fous que JSON atteint seulement par convention.

Versioning et évolution du schéma sans casser les clients

Les APIs évoluent : vous ajoutez des champs, ajustez des comportements et mettez fin à des parties anciennes. L'objectif : changer le contrat sans surprendre les consommateurs.

Compatibilité descendante vs ascendante (en clair)

• Compatibilité descendante : les nouveaux serveurs peuvent parler aux anciens clients. Les anciens clients ignorent ce qu'ils ne comprennent pas.
• Compatibilité ascendante : les nouveaux clients peuvent parler aux anciens serveurs. Les nouveaux clients gèrent l'absence de champs et utilisent des valeurs par défaut.

Une bonne stratégie vise les deux, mais la compatibilité descendante est souvent le minimum requis.

Protobuf : les numéros de champ sont l'identité réelle

En Protobuf, chaque champ a un numéro (ex. email = 3). Ce numéro—et non le nom du champ—est ce qui est envoyé sur le fil. Les noms servent surtout aux humains et au code généré.

De là découlent :

• Changements sûrs (en général)

  • Ajouter des champs optionnels avec de nouveaux numéros jamais utilisés.
  • Ajouter des valeurs d'enum (sans réordonner les existantes si possible).
  • Marquer un champ comme déprécié (le garder mais arrêter de l'utiliser), et réserver son numéro.

• Changements risqués (souvent cassants)

  • Réutiliser un numéro de champ pour une autre signification ou un autre type.
  • Changer le type d'un champ de façon incompatible (string → int).
  • Supprimer un champ sans réserver son numéro (une réutilisation future corrompra le sens).
  • Renommer est sûr sur le fil, mais peut casser le code généré et des hypothèses en aval.

Bonne pratique : utilisez reserved pour les anciens numéros/noms et tenez un changelog.

JSON : versioning par conventions et discipline

JSON n'a pas de schéma intégré, donc la compatibilité dépend de vos pratiques :

• Favorisez les changements additifs : ajoutez des champs plutôt que d'en modifier.
• Traitez les champs inconnus comme ignorables, et les champs manquants comme « utiliser une valeur par défaut raisonnable ».
• Évitez de changer les types ; si nécessaire, introduisez un nouveau nom de champ.

Dépréciations et politique claire

Documentez les dépréciations tôt : quand un champ est marqué obsolète, combien de temps il sera supporté et par quoi il est remplacé. Publiez une politique de versioning simple (ex. « changements additifs = non cassant ; suppressions = nouvelle version majeure ») et appliquez-la.

Outils et écosystème selon les plateformes

Choisir entre JSON et Protobuf dépend souvent de l'endroit où votre API doit fonctionner—et de ce que votre équipe veut maintenir.

Navigateurs vs serveurs : l'avantage « par défaut » de JSON

JSON est pratiquement universel : chaque navigateur et runtime backend peut le parser sans dépendance supplémentaire. Dans une app web, fetch() + JSON.parse() est le parcours le plus simple, et les proxies, gateways et outils d'observabilité comprennent souvent JSON par défaut.

Protobuf peut fonctionner en navigateur aussi, mais ce n'est pas gratuit. Il faut généralement ajouter une bibliothèque Protobuf (ou du code JS/TS généré), gérer la taille du bundle et décider si vous envoyez Protobuf sur des endpoints HTTP que vos outils de navigation peuvent inspecter.

Mobile et SDK backend : où Protobuf brille

Sur iOS/Android et dans les langages backend (Go, Java, Kotlin, C#, Python, etc.), le support Protobuf est mature. La différence clé : Protobuf suppose l'utilisation de bibliothèques par plateforme et la génération de code à partir des .proto.

La génération de code apporte de réels bénéfices :

• Modèles typés et enums, avec des erreurs détectées plus tôt quand les clients divergent du contrat
• Bibliothèques de sérialisation rapides et formes de données cohérentes entre services

Elle ajoute aussi des coûts :

• Étapes de build (générer le code en CI, garder les artefacts en phase)
• Complexité de repo/process (publier des packages .proto partagés, verrouiller des versions)

gRPC : un écosystème fort, une contrainte structurante

Protobuf est étroitement lié à gRPC, qui offre une histoire d'outillage complète : définitions de services, stubs clients, streaming et interceptors. Si vous envisagez gRPC, Protobuf est le choix naturel.

Si vous construisez une API REST JSON traditionnelle, l'écosystème JSON (DevTools navigateur, debugging curl-friendly, gateways génériques) reste plus simple—surtout pour des APIs publiques et des intégrations rapides.

Prototyper les deux options sans s'engager trop tôt

Si vous explorez encore la surface d'API, il peut être utile de prototyper dans les deux styles avant de standardiser. Par exemple, des équipes utilisant Koder.ai prototypent souvent une API REST JSON pour compatibilité large et un service interne gRPC/Protobuf pour l'efficacité, puis benchmarkent les charges réelles avant de choisir le mode par défaut. Comme Koder.ai peut générer des apps full-stack (React web, Go + PostgreSQL backend, Flutter mobile) et supporte le mode planning et les snapshots/rollbacks, il est pratique d'itérer sur les contrats sans transformer la décision de format en refactor massif.