web-dev-qa-db-fra.com

Les valeurs nulles doivent-elles être incluses dans les réponses JSON d'une API REST?

Je suis en train de concevoir et de développer une API RESTful. J'adopte une approche pragmatique et orientée ressources de l'API (orientée ressources, interface uniforme, adressabilité, mais pas de véritable HATEOAS). Cependant, je ne suis pas sûr de savoir comment aborder les valeurs nulles dans les objets.

Dois-je inclure des champs avec des valeurs nulles dans les réponses des API?

Exemple:

{
    "fieldA": "AAA",
    "fieldB": null
}

Ou, dois-je simplement laisser ces champs complètement si le système n'a pas de données pour ces champs?

Exemple:

{
    "fieldA": "AAA"
}
jsonapirest
42
Dennis Laumen

Il y a eu une discussion à ce sujet récemment sur API-Craft . Le consensus général était qu'il existe potentiellement une différence sémantique entre l'omission d'une valeur, et l'inclusion d'une valeur nulle.

S'il n'y a pas de valeur sémantique à gagner pour votre cas d'utilisation spécifique, je dirais que regardez vos consommateurs cibles de l'API et demandez-vous si l'omission de la valeur leur causera des problèmes.

22
Pete

Il n'y a pas de vainqueur clair. Et parce qu'il n'y en a pas, les clients ne devraient jamais dépendre techniquement d'une convention à ce sujet, les clients ne devraient pas s'attendre à l'une ou l'autre forme.

  • supprimer les valeurs nulles pour réduire l'utilisation de la bande passante n'est généralement pas justifié (à moins que le nombre de champs nuls soit grand et que la bande passante en souffre sensiblement).
  • supprimer les valeurs nulles pour permettre aux lecteurs humains de voir plus facilement les valeurs réelles n'est pas généralement justifié, les API ne sont pas des interfaces homme-machine
  • conserver les valeurs nulles pour permettre aux lecteurs humains de voir plus facilement la structure du document n'est pas généralement justifié, les API ne sont pas des interfaces homme-machine et les réponses des API ne sont pas de la documentation API
  • garder les valeurs nulles pour permettre aux clients sales d'analyser le json de manière spécifique n'est généralement pas justifié, les clients doivent être écrits proprement en tant que lecteurs tolérants
  • conserver les valeurs nulles uniquement lorsque la méthode de création correspondante (POST/PUT) nécessite le passage explicite de null aurait du sens, mais est généralement difficile à réaliser
  • en gardant la sortie identique à la demande lors de la création pourrait avoir un sens lorsque chaque document a son propre client propriétaire, mais est généralement difficile à réaliser
  • Un cas particulier à considérer est les réponses partielles déclenchées par quelque chose comme ?fields=foo,bar où retourner des valeurs nulles pour tous les autres champs semble un peu contre-intuitif
8
tkruse