Why you should avoid returning lists in API?

En tant que développeurs backend, nous passons une grande partie de notre temps à créer des APIs. 

La création d’APIs flexibles et maintenables est cruciale pour assurer la satisfaction des consommateurs et faciliter les évolutions futures. 

Une pratique courante, mais souvent problématique, consiste à renvoyer directement une liste JSON dans les réponses de l’API. 

Dans cet article, nous allons examiner pourquoi encapsuler les réponses dans un objet JSON est une bonne pratique et comment cela peut améliorer la qualité de votre API.

Flexibilité et Extensibilité

Facilité d’ajout de nouvelles données

Lorsque vous encapsulez la réponse dans un objet JSON, il est beaucoup plus facile d’ajouter de nouvelles informations sans rompre la compatibilité avec les clients existants. 

Par exemple, si vous souhaitez ajouter des informations de pagination ou des métadonnées, vous pouvez simplement ajouter de nouveaux champs à l’objet JSON.
Cela évite les problèmes de compatibilité rétroactive.

{
  "students": [
    {
      "name": "Fabrice",
      "level": "Expert"
    },
    {
      "name": "Alice",
      "level": "Junior"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "currentPage": 1,
  "links": {
    "self": "/api/v1/students?page=1",
    "next": "/api/v1/students?page=2"
  }
}

Clarté et Structure

Organisation

En encapsulant les données de réponse dans un objet, vous créez une structure claire et bien définie. Cela facilite la compréhension pour les consommateurs de l’API, car ils peuvent facilement naviguer et extraire les données nécessaires. Cette organisation structurée réduit également les risques d’erreurs lors de l’utilisation de l’API.

Gestion des Erreurs et des Métadonnées

Messages d’erreur

Avec un objet JSON, vous pouvez inclure des messages d’erreur, des codes de statut, et d’autres informations pertinentes directement dans la réponse. Cela permet aux clients de gérer les erreurs de manière plus efficace et d’avoir une meilleure compréhension de ce qui ne va pas.

{
  "students": [],
  "error": {
    "code": 404,
    "message": "No students found"
  }
}

Uniformité et Standardisation

Consistance des réponses

En adoptant un format standard pour toutes les réponses, vous assurez une consistance à travers toute l’API. Les clients savent toujours à quoi s’attendre, ce qui facilite le développement et le débogage. Cette uniformité améliore également la documentation de l’API et la compréhension pour les nouveaux développeurs.

Support des Hypermédias (HATEOAS)

HATEOAS

L’approche RESTful préconise l’utilisation de liens hypermédia pour guider les clients sur les actions possibles. Utiliser un objet JSON facilite l’inclusion de tels liens, permettant aux clients de découvrir et d’interagir avec l’API de manière dynamique.

{
  "students": [
    {
      "name": "Alice",
      "level": "Sophomore",
      "links": {
        "self": "/api/v1/students/1",
        "courses": "/api/v1/students/1/courses"
      }
    }
  ],
  "links": {
    "self": "/api/v1/students",
    "next": "/api/v1/students?page=2"
  }
}

Préparation pour les Futures Évolutions

Évolution de l’API

Les APIs évoluent souvent avec le temps. En encapsulant les réponses dans des objets JSON, vous préparez l’API à évoluer sans casser la compatibilité avec les clients existants. 

Vous pouvez déprécier certains champs et en introduire de nouveaux progressivement, ce qui facilite la gestion des versions.

Conclusion

Utiliser un objet JSON pour encapsuler les réponses d'une API REST offre de nombreux avantages, notamment en termes de flexibilité, de clarté, de gestion des erreurs, et de support des hypermédias. Cette pratique améliore globalement la qualité, la maintenabilité, et la robustesse de votre API, tout en préparant le terrain pour des évolutions futures. En adoptant cette approche, vous assurez une meilleure satisfaction des consommateurs et une plus grande facilité de développement pour les mainteneurs de l'API. 

Adoptez dès maintenant cette pratique pour vos projets et observez la différence en termes de flexibilité et de maintenabilité de vos APIs REST.