🎯 Intention

<aside> ✅

Pré-requis

• Connaitre le format JSON
• Connaitre le protocole HTTP (headers, body, response, code, etc) </aside>

✅ Points clés

<aside> ⌛ Temps indicatif : 0.5j

</aside>

Etape

Visuel / Exemple

🆎 Définir une conventions de nommage unique

• Choisir une convention de nommage globale : underscore_case

Raison :

Pour l’instant on ne sait pas comment faire pour renvoyer et écouter du camelCase sur un projet Ruby on Rails, c’est pour cela que nous avons choisi underscore_case

❌ BAD
{
  "lastName": "Toto"
}

✅ GOOD
{
  "last_name": "Toto"
}

🆗 Définir le format des réponses de type “Succès“

• Suivre la spec des code d’erreurs HTTP (Code 2xx)
• Pour PUT et POST renvoyer l’objet modifié
• la suppression d’un objet (destroy) retourne un code : 204 No content

Raison :

La réponse doit être le plus explicite possible.

• Exemple d’implémentation d’une réponse pour une collection (index)
• Exemple d’implémentation d’une réponse pour un objet (show/create/update)

🛑 Définir le format des réponses de type “Erreur”

• Utiliser la gem captive-api pour catcher les erreurs

Raison :

Avoir un format d’erreur générique permet de facilement envoyer toutes les informations nécessaire au débuggage au client.

{
	"message": "Impossible de faire XXX",
	"errors": {
    "template_tenue": [
      "doit exister"
    ],
    "bloc_rouge": [
      "doit exister"
    ],
    "bloc_vert": [
      "doit exister"
    ]
  },
	"code": "unprocessable_entity",
}

❌ Erreurs type à éviter

• Inventer un nouveau protocole : la plupart des use-cases ont déjà été couvert par des entreprises (search, pagination, offline, etc).

🎓Aller plus loin

Spec des codes de retour HTTP commun