Pourquoi j’ai arrêté d’utiliser JSON dans mon API pour passer à Protobuf

• JSON, devenu le standard des API web, est facile à lire et flexible, mais présente des limites en matière de performance et de fiabilité
• Protobuf (Protocol Buffers) garantit clairement la structure des données grâce à une définition de types stricte et à la génération automatique de code
• Grâce à la sérialisation binaire, il réduit la taille des données d’environ 3 fois ou plus par rapport à JSON et améliore la vitesse de transfert
• Le serveur et le client partagent le même schéma .proto, ce qui élimine les incompatibilités de types et le besoin de validations manuelles
• Le débogage est plus difficile, mais en matière de performance, maintenabilité et efficacité de développement, Protobuf convient mieux aux API modernes

---

L’universalité et les limites de JSON

• JSON est un format texte facile à lire par les humains : un simple console.log() suffit pour inspecter les données
• Grâce à son intégration parfaite avec le web, il est largement adopté dans JavaScript comme dans les frameworks backend
• Il offre une grande flexibilité, avec la possibilité d’ajouter ou supprimer des champs et de modifier les types, mais cela ouvre aussi la porte aux incohérences de structure et aux erreurs
• Son écosystème d’outils est riche, et il se manipule facilement avec un éditeur de texte ou curl
• Malgré ces avantages, il existe de meilleures alternatives en matière de performance et de sûreté des types

Vue d’ensemble de Protobuf

• Un format de sérialisation binaire développé par Google en 2001 et rendu public en 2008
• Largement utilisé dans les systèmes internes et pour la communication entre microservices
• On pense souvent à tort qu’il faut l’utiliser avec gRPC, alors que Protobuf peut aussi être utilisé de manière autonome dans des API HTTP
• Au départ, sa faible lisibilité due au format binaire le rendait moins accessible, mais il présente de forts avantages en matière d’efficacité et de fiabilité

Un système de types puissant et la génération de code

• Protobuf définit clairement la structure des données via des fichiers .proto
  • Chaque champ possède un type strict, un identifiant numérique et un nom fixe
• Exemple :

  message User {
    int32 id = 1;
    string name = 2;
    string email = 3;
    bool isActive = 4;
  }
  

• La commande protoc prend en charge la génération automatique de code dans de nombreux langages, dont Dart, TypeScript, Kotlin, Swift, C#, Go et Rust
• Le code généré permet d’effectuer la sérialisation (writeToBuffer) et la désérialisation (fromBuffer) sans validation ni parsing manuels
• Au final, on gagne à la fois en temps et en maintenabilité

L’efficacité de la sérialisation binaire

• Protobuf sérialise les données en binaire plutôt qu’en texte, ce qui le rend très compact et rapide
• Comparaison de taille pour les mêmes données (objet User) :
  • JSON : 86 octets (68 octets sans espaces)
  • Protobuf : 30 octets
• Cette efficacité s’explique par :
  • l’utilisation de l’encodage varint pour les nombres
  • l’usage de tags numériques au lieu de clés texte
  • la suppression des espaces et de la syntaxe superflue
  • l’optimisation des champs optionnels
• Résultat : moins de bande passante consommée, temps de réponse amélioré, économie de données mobiles et meilleure expérience utilisateur

Exemple d’API Protobuf basée sur Dart

• Le package shelf permet de mettre en place un serveur HTTP simple qui renvoie un objet User en Protobuf
• Points clés du code serveur :
  • création d’un objet User(), puis sérialisation avec writeToBuffer()
  • définition de l’en-tête de réponse 'content-type': 'application/protobuf'
• Le client utilise le package http et user.pb.dart pour décoder directement les données Protobuf
• Comme le serveur et le client partagent le même schéma .proto, aucune incohérence de structure de données ne survient
• La même approche s’applique aussi en Go, Rust, Kotlin, Swift, C#, TypeScript, etc.

Les avantages restants de JSON

• Avec Protobuf, il est difficile d’interpréter le sens sans schéma
  • Au lieu de noms de champs, seuls des identifiants numériques apparaissent, ce qui le rend difficile à lire pour un humain
• Exemple de comparaison :
  • JSON : { "id": 42, "name": "Alice" }
  • Protobuf : 1: 42, 2: "Alice"
• Par conséquent, Protobuf nécessite :
  • des outils de décodage dédiés
  • une gestion du schéma et du versioning rigoureuse
• Malgré cela, les gains en performance et en efficacité sont bien supérieurs

Conclusion

• Protobuf est une technologie de sérialisation mature et haute performance, parfaitement exploitable même dans des API publiques
• Il fonctionne de manière autonome dans une API HTTP classique, sans gRPC
• C’est un outil qui améliore à la fois les performances, la robustesse, la réduction des erreurs et l’efficacité de développement
• Il mérite clairement d’être envisagé dans les projets de nouvelle génération