4. Organiser la structure des réponses

On a bien avancé depuis le début du chapitre, puisque désormais nous sommes capables de retourner des réponses au format JSON depuis notre API Rest.

Cependant, bien que notre réponse soit au bon format, est-elle assez complète pour autant ?

Par exemple, lorsqu’on retourne les données d’un pokémon, on renvoie bien les bonnes informations. Pour autant, si on se met à la place des développeurs frontend qui consommeront notre API Rest, ce serait sympas de leur confirmer que tout s’est bien déroulé, sous la forme d’un petit message supplémentaire dans la réponse JSON.

De même lorsque nous aurons une erreur au niveau de notre API Rest, nous pourrons nous servir de ce message supplémentaire pour donner un peu plus de détails sur les causes de cette erreur.

Et rappelez-vous, on juge une API Rest à la qualité et à la fiabilité de ses réponses. On ne pourra JAMAIS vous reprocher d’être « trop » précis. 😉

On va donc mettre en place une nouvelle « méthode-outil », qui sera chargée de créer une réponse sur mesure pour nos points de terminaisons, contenant à la fois les données et un court message explicatif. J’ai prévu de créer un module JavaScript à part, afin de ne pas surcharger en code le point d’entrée de notre code.

Créer donc un nouveau fichier helper.js, à la racine de votre projet :

const success = (message, data) => {
  return {
    message: message,
    data: data
  }
}
 
exports.success

Ce module est très simple. On déclare une méthode success qui prend deux paramètres en compte pour construire une nouvelle réponse JSON, mieux structurée :

  • Un message concis de description.
  • Les données brutes en tant que telle, attendues par le consommateur.

Ensuite, on exporte la méthode success à la dernière ligne.

Mais pourquoi avoir créé un module entier, pour une unique méthode… Ce n’est pas un peu exagéré, non ?

Pour le moment, effectivement cela peut sembler « un peu trop ». Mais par la suite, on va surement devoir créer une méthode supplémentaire pour la gestion des erreurs. On pourra donc placer cette méthode directement dans ce module helper. Pratique !  👍

D’ailleurs, tant qu’on y est, ne pourrait-on pas raccourcir encore le code de helper.js ? Je vous propose d’exposer directement notre méthode, grâce à la syntaxe des modules CommonJS :

// Recommandé
exports.success = (message, data) => {
  return { 
    message: message,
    data: data
  }
}

Excellent excellent… mais ce n’est pas finit !

Nous pouvons encore écrire du code plus concis, et sans perdre en lisibilité. Et ce n’est pas de la magie.

En fait, il existe une syntaxe assez efficace d’ECMAScript 6, permettant de fusionner la propriété et la valeur d’un objet JavaScript, s’ils ont le même nom. Ce n’est pas forcément clair la première fois, alors prenons un exemple pour mieux comprendre :

// On déclare une simple constante.
const name = 'Bulbizarre'
 
// SANS le raccourci de syntaxe ECMAScript 6.
const pokemon = { name: name }
 
// Avec le raccourci de syntaxe ECMAScript 6.
const pokemon = { name }

Croyez-le ou non, mais vous avez le droit d’écrire le code avec ce raccourci de syntaxe. Cela permet non seulement d’écrire moins de code, mais également élimine le risque de faire des erreurs de frappe. Si nous l’appliquons à notre module helper.js, on obtiens ceci :

// Encore plus loin (mais on met pas ça dans notre code !)
exports.success = (message, data) => {
  return { message, data }
}

Nous sommes passés à seulement 3 lignes de code pour notre module helper. Alors, si cette syntaxe vous semble illisible ou complexe, cela est normal au début, il faudra un peu de temps pour s’adapter. Mais ça vaut le coup pour la suite de votre vie de développeur, vous serez beaucoup plus efficace. Et puis vous savez comme il est difficile de changer ses habitudes une fois celle-ci prise. C’est beaucoup plus simple de mettre les pendules à l’heure dès le début.

Bon, c’étais un peu plus long que d’habitude, mais ça valait le coup. Maintenant que l’on a ce qu’il faut, il nous reste encore à utiliser ce nouveau module !