JSON API
  • Créé par le co-fondateur de http://www.tilde.io, une entreprise de conseil (en jsonapi ?).
  • C’est une spécification et non un standard.
1
{
2
"links": {
3
"self": "http://example.com/articles",
4
"next": "http://example.com/articles?page[offset]=2",
5
"last": "http://example.com/articles?page[offset]=10"
6
},
7
"data": [{
8
"type": "articles",
9
"id": "1",
10
"attributes": {
11
"title": "JSON API paints my bikeshed!"
12
},
13
"relationships": {
14
"author": {
15
"links": {
16
"self": "http://example.com/articles/1/relationships/author",
17
"related": "http://example.com/articles/1/author"
18
},
19
"data": {"type": "people", "id": "9"}
20
},
21
"comments": {
22
"links": {
23
"self": "http://example.com/articles/1/relationships/comments",
24
"related": "http://example.com/articles/1/comments"
25
},
26
"data": [
27
{"type": "comments", "id": "5"},
28
{"type": "comments", "id": "12"}
29
]
30
}
31
},
32
"links": {
33
"self": "http://example.com/articles/1"
34
}
35
}],
36
"included": [{
37
"type": "people",
38
"id": "9",
39
"attributes": {
40
"first-name": "Dan",
41
"last-name": "Gebhardt",
42
"twitter": "dgeb"
43
},
44
"links": {
45
"self": "http://example.com/people/9"
46
}
47
}, {
48
"type": "comments",
49
"id": "5",
50
"attributes": {
51
"body": "First!"
52
},
53
"relationships": {
54
"author": {
55
"data": {"type": "people", "id": "2"}
56
}
57
},
58
"links": {
59
"self": "http://example.com/comments/5"
60
}
61
}, {
62
"type": "comments",
63
"id": "12",
64
"attributes": {
65
"body": "I like XML better"
66
},
67
"relationships": {
68
"author": {
69
"data": {"type": "people", "id": "9"}
70
}
71
},
72
"links": {
73
"self": "http://example.com/comments/12"
74
}
75
}]
76
}
Copied!

Cool 👍

  • Définition d’un format strict mais extensible.
  • Standardisation des paramètres de sorting, filtering et de pagination (l’implémentation reste libre pour la pagination).
  • L’idée du resource linking avec des relationships est intéressante.

Pas cool 👎

  • Risque de collision entre les fields présents dans attributes et relationships.
  • Pas de différence entre un lien vers une instance ou une collection.
  • Les one-to-one relationships sont ambigües et ne respectent pas la convention : /resources/:resourceId/sub-resources/:subResourceId
  • Attention, les exemples utilisés dans la spec adoptent des conventions inhabituelles et ne sont pas imposés par la spec.
    • L’utilisation des fields en kebab-case n’est pas dans le standard.
    • La propriété type n’est pas forcément au pluriel.
  • L’idée des bulk operations sur les relationships est très intéressante mais malheureusement pas appliquée aux ressources.
  • De nombreuses implémentations mais la plupart ne sont plus maintenues depuis des mois voire des années.
Dernière mise à jour 2yr ago
Copier le lien