Quelle est la meilleure façon de renvoyer un tableau en réponse dans une API RESTful?
Supposons que nous ayons des ressources comme celle-ci,
book:
type: object
properties:
author: {type: string}
isbn: {type: string}
title: {type: string}
books:
type: array
items: book
Ainsi, lorsque quelqu'un crée un GET sur la ressource livres, nous renvoyons ce qui suit
[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
J'ai entendu quelqu'un au travail que la pratique recommandée REST consiste à toujours renvoyer les réponses en tant qu'objets JSON, ce qui signifierait que notre schéma pour books ressemblerait à ceci,
books:
type: object
properties:
list:
type: array
items: book
Donc, maintenant, la réponse ressemblerait à ceci,
{
"list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}
Laquelle de ces méthodes est la meilleure REST pratique?
En pratique, la deuxième option est la meilleure pratique. La raison en est que vous ne pouvez pas du tout étendre la ressource lorsque vous retournez simplement un tableau.
Par exemple: si vous devez ajouter un nombre de tous les enregistrements, vous avez déjà terminé avec l'approche tableau uniquement.
Si cela se produit dans une seule API de liste, vous voulez le garder cohérent, alors faites tout un objet, puis votre API devient plus cohérente et plus facile à utiliser pour les développeurs.
Par exemple: supposons qu'un développeur écrit du code générique pour utiliser votre API pour afficher les pages de liste et de détail. Il ne veut pas construire d'exception car parfois c'est un tableau et parfois c'est un objet avec une propriété list.
Au total, cette réponse n'a rien à voir avec les principes de repos, de hateoas et d'autres protocoles, mais elle est juste réelle concernant les données que vous devez envoyer au client. Si vous décidez de suivre par exemple les hateos, alors bien sûr, respectez leurs normes (qui sont également des objets btw).
Tous les deux
[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
et
{
"list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}
sont des Json valides. Je ne pense pas que vous devriez ajouter "liste" si ce n'est pas nécessaire, cela pourrait même être déroutant car ce qui le suit est un tableau, au lieu d'une liste.
Meilleure REST? L'API doit donner une réponse appropriée à tout ce qui est défini dans l'en-tête Accept, ainsi qu'une bonne documentation.
La raison pour laquelle vous répondez à JSON est que JSON est un standard de facto; n'importe quelle langue avec un analyseur JSON peut l'analyser trivialement, et si vous utilisez JavaScript, vous n'avez même pas besoin d'un analyseur puisque JavaScript le comprend nativement.
En d'autres termes, rendez-le compatible JSON et vous n'aurez pas à écrire votre propre analyseur. De plus, il n'y aura pas de surprise lorsque le prochain développeur écrit un logiciel qui utilise le service.
REST n'a rien à voir avec votre schéma JSON. L'un ou l'autre schéma est acceptable, du point de vue REST.
La deuxième option est également la méthode préférée pour des raisons de sécurité. Les navigateurs plus anciens ont une vulnérabilité de sécurité qui permet à d'autres codes javascript sur la page Web de voler vos données si elles sont renvoyées sous forme de tableau JSON. Historiquement, la meilleure pratique consistait donc à ne pas renvoyer de tableaux JSON. En fait, il y avait certains frameworks dont la fonction "json-ify" choisit l'option 2 par défaut lorsque vous passez dans un tableau.
Un dictionnaire avec une seule "liste" de clés sans signification et une valeur de tableau est inutile - renvoyez un tableau à la place.
Si le même service peut renvoyer des livres, des CD ou des DVD, vous pouvez renvoyer un dictionnaire avec une clé "livres" et une valeur de tableau. Il pourrait y avoir une autre clé "DVD" avec une gamme de DVD. Par exemple, si un client peut demander une liste de tous ses achats.
Si vous êtes certain que la réponse ne sera interprétée que comme une liste de livres (si la demande disait "donnez-moi une liste de livres"), alors un simple tableau suffit.
les deux sont json et adhèrent à REST. Je voudrais rendre la réponse plus descriptive, dans votre cas, changez la liste en livres. Ou quelque chose comme ça :
{ "responceObject" : {
results : 2,
"Books": [
{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}
]
}}