> For the complete documentation index, see [llms.txt](https://guide-api-rest.marmicode.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide-api-rest.marmicode.fr/autres-specifications/json-api.md).

# JSON API

<http://jsonapi.org/>

* Créé par le co-fondateur de [http://www.tilde.io](http://www.tilde.io/), une entreprise de conseil *(en jsonapi ?).*
* C’est une spécification et non un standard.

```javascript
{
    "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.

�


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide-api-rest.marmicode.fr/autres-specifications/json-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.