clakech/gist:34aef266419a1bd9c131

Une API doit elle forcément être consistante et cohérente dans ses représentations ou bien peut elle adapter la représentation des attributs en fonction de leur type ?

Dans cet exemple, on voit que l'attribut title a des valeurs sous forme de tableau de string mais l'attribut images a pour valeurs des map de href et l'attribut relatives a pour valeur des maps de href, name et age.

Du coup, le lecteur de cet API n'a pas toujours le même type de données dans l'attribut values.

C'est simple pourtant, il évoque la théorie du typage implicite... Je m'explique, si un Cock est capable de rentrer dans un dameer, est-il envisageable qu'on puisse y introduire d'autres objets non typés ? par exemple un objet pad seylaanyenta sans methode WD40 ? C'est très sérieux et mérite qu'on en fasse un sujet de thèse.

Je dirais que ce n'est pas déconnant.

• Les attributs de la ressource même sont forme d'une simple map ; L'URL étant celle de la ressource même, elle est précisée tout en haut et n'est pas répétée.
• Les relations vers les autres ressources (images, relatives) sont également sous forme de map, avec une URL obligatoire (HATEOAS-style) et des attributs optionnels (comme pour tes "relatives").

Ca peut paraître bizarre ou incohérent parce que tes images n'ont ici que leur URL de ressource, mais si elles avaient également des attributs (taille, légende...), tu verrais mieux la cohérence de la structure.

OK. Ce qui est gênant c'est que parfois values contient des strings comme pour title et parfois des objets comme pour relatives. Du coup on ne sait pas quel type on va trouver dans values. Ça ne te dérange pas toi?

Humm sur cet exemple précis, non.
Values est de toute façon toujours un tableau, qui contient :

• soit un type simple ou tableau de types simples, comme les titres ; en Java, on aurait une List par exemple.
• soit un tableau de ressources liées, qui sont des objets complexes (~List, List). Dans ce cas, cela a du sens de les représenter sous forme de maps.

Si tu connais la structure de ta ressource (ex: elle possède N attributs simples nommés x,y,z, et des relations vers d'autres entités A,B,C), ce n'est pas très difficile à parser. Par contre, si tu découvres la structure quand tu la parses, effectivement, tu es obligé de vérifier dynamiquement le type de la valeur, et je t'accorde que c'est pénible.

@clakech T'es certain qu'il faut mettre les collections aux pluriel ?

La structure de la ressource n'est pas connue à l'avance... C'est en la parcourant qu'on découvre le type de chaque values

C'est vrai qu'il aurait mieux valu séparer les valeurs propres de l'entité, de ses relations.
Ainsi, pour les attributs propres, on saurait qu'il faut récucpérer un type simple, ou un tableau de types simples ; et pour les relations, on saurait qu'il faut récupérer une map.

{
    "id": "4d49ca82",
    "attributes": [
        {
            "name": "title",
            "values": ["Find the rabbit"]
        }
    ],
    "relations": [
        {
            "name": "images",
            "values": [
                {
                    "href": "/images/b28551d4",
                    "caption": "Hello"
                },
                {
                    "href": "/images/dsfg879",
                    "caption": "World"
                }
            ]
        },
        {
            "name": "relatives",
            "values": [
                {
                    "href": "/relatives/b28551d4",
                    "name": "Olga Rismov",
                    "age": 23
                },
                {
                    "href": "/relatives/f8984f",
                    "name": "Igor N.",
                    "age": 46
                }
            ]
        }
    ]
}

La question ne serait-elle pas : "La consistance dans la représentation des attributs rendrait-elle l'api plus lisible et plus pratique à utiliser ?"
Si la réponse est oui, alors il y a des améliorations à faire...
Mais si pour l'usage donné cette représentation était la plus pratique, alors le choix était le bon! Pragmatisme 👍 ;-)

Bref, si tu ne la trouves pas pratique, c'est qu'elle ne l'est pas.

Alexandre Bertails était passé au Bordeaux JUG nous expliquer JSON-LD, une sorte de XML Schema adapté à JSON. Ca permet de définir la structure et le type des attributs de chaque entité, au sein d'un contexte particulier. Au moins avec ça, on sait ce qu'on parse.

http://json-ld.org/