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.