JSON API

​http://jsonapi.org/​

  • 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.

{
"links": {
"self": "http://example.com/articles",
"next": "http://example.com/articles?page[offset]=2",
"last": "http://example.com/articles?page[offset]=10"
},
"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/articles/1/relationships/author",
"related": "http://example.com/articles/1/author"
},
"data": {"type": "people", "id": "9"}
},
"comments": {
"links": {
"self": "http://example.com/articles/1/relationships/comments",
"related": "http://example.com/articles/1/comments"
},
"data": [
{"type": "comments", "id": "5"},
{"type": "comments", "id": "12"}
]
}
},
"links": {
"self": "http://example.com/articles/1"
}
}],
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"relationships": {
"author": {
"data": {"type": "people", "id": "2"}
}
},
"links": {
"self": "http://example.com/comments/5"
}
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"
},
"relationships": {
"author": {
"data": {"type": "people", "id": "9"}
}
},
"links": {
"self": "http://example.com/comments/12"
}
}]
}

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.

​