You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: faq/index.md
+12-12Lines changed: 12 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ title: Frequently Asked Questions
4
4
show_sidebar: true
5
5
---
6
6
7
-
## <ahref="#what-is-the-meaning-of-json-apis-version"id="what-is-the-meaning-of-json-apis-version"class="headerlink"></a> What is the meaning of JSONAPI's version?
7
+
## <ahref="#what-is-the-meaning-of-json-apis-version"id="what-is-the-meaning-of-json-apis-version"class="headerlink"></a> What is the meaning of JSON:API's version?
8
8
9
-
Now that JSONAPI has reached a stable version 1.0, it will always be
9
+
Now that JSON:API has reached a stable version 1.0, it will always be
10
10
backwards compatible using a _never remove, only add_ strategy.
11
11
12
12
A version is maintained in order to:
@@ -18,22 +18,22 @@ A version is maintained in order to:
18
18
19
19
There are several reasons:
20
20
21
-
* HAL embeds child documents recursively, while JSONAPI flattens the entire
21
+
* HAL embeds child documents recursively, while JSON:API flattens the entire
22
22
graph of objects at the top level. This means that if the same "people" are
23
23
referenced from different kinds of objects (say, the author of both posts and
24
24
comments), this format ensures that there is only a single representation of
25
25
each person document in the payload.
26
-
* Similarly, JSONAPI uses IDs for linkage, which makes it possible to cache
26
+
* Similarly, JSON:API uses IDs for linkage, which makes it possible to cache
27
27
documents from compound responses and then limit subsequent requests to only
28
28
the documents that aren't already present locally. If you're lucky, this can
29
29
even completely eliminate HTTP requests.
30
30
* HAL is a serialization format, but says nothing about how to update
31
-
documents. JSONAPI thinks through how to update existing records (leaning on
31
+
documents. JSON:API thinks through how to update existing records (leaning on
32
32
PATCH and JSON Patch), and how those updates interact with compound documents
33
33
returned from GET requests. It also describes how to create and delete
34
34
documents, and what 200 and 204 responses from those updates mean.
35
35
36
-
In short, JSONAPI is an attempt to formalize similar ad hoc client-server
36
+
In short, JSON:API is an attempt to formalize similar ad hoc client-server
37
37
interfaces that use JSON as an interchange format. It is specifically focused
38
38
around using those APIs with a smart client that knows how to cache documents it
39
39
has already seen and avoid asking for them again.
@@ -54,7 +54,7 @@ For instance, a client might request `HEAD /articles`, and the response could
54
54
contain the header `Allow: GET,POST`, indicating that the client can GET the
55
55
collection and also POST to it to create new resources.
56
56
57
-
JSONAPI is still working on a way to for resources to advertise and detail
57
+
JSON:API is still working on a way to for resources to advertise and detail
58
58
non-standard actions they support. Feel free to
59
59
[join that discussion](https://github.com/json-api/json-api/issues/745)!
60
60
@@ -71,15 +71,15 @@ Instead, PUT is supposed to completely replace the state of a resource:
71
71
target resource will result in an equivalent representation being sent…”
72
72
73
73
The correct method for partial updates, therefore, is [PATCH](http://tools.ietf.org/html/rfc5789),
74
-
which is what JSONAPI uses. And because PATCH can also be used compliantly for
75
-
full resource replacement, JSONAPI hasn't needed to define any behavior for
74
+
which is what JSON:API uses. And because PATCH can also be used compliantly for
75
+
full resource replacement, JSON:API hasn't needed to define any behavior for
76
76
PUT so far. However, it may define PUT semantics in the future.
77
77
78
78
In the past, many APIs used PUT for partial updates because PATCH wasn’t yet
79
79
well-supported. However, almost all clients now support PATCH, and those that
80
80
don’t can be easily [worked around](/recommendations/#patchless-clients).
81
81
82
-
## <ahref="#is-there-a-json-schema-describing-json-api"id="is-there-a-json-schema-describing-json-api"class="headerlink"></a> Is there a JSON Schema describing JSONAPI?
82
+
## <ahref="#is-there-a-json-schema-describing-json-api"id="is-there-a-json-schema-describing-json-api"class="headerlink"></a> Is there a JSON Schema describing JSON:API?
83
83
84
84
Yes, you can find the JSON Schema definition at
85
85
[http://jsonapi.org/schema](http://jsonapi.org/schema). This schema is as
@@ -104,6 +104,6 @@ than type because it's possible that a primary resource may have related
104
104
resources of the same type (e.g. the "parents" of a "person"). Nesting related
105
105
resources in `included` prevents this possible conflict.
106
106
107
-
## <ahref="#position-uri-structure-custom-endpoints"id="position-uri-structure-custom-endpoints"class="headerlink"></a> Does JSONAPI take any position on URI structure, on rules for custom endpoints, which do not fit the paradigm of GET/POST/PATCH/DELETE on the resource URI, etc.?
107
+
## <ahref="#position-uri-structure-custom-endpoints"id="position-uri-structure-custom-endpoints"class="headerlink"></a> Does JSON:API take any position on URI structure, on rules for custom endpoints, which do not fit the paradigm of GET/POST/PATCH/DELETE on the resource URI, etc.?
108
108
109
-
JSONAPI has no requirements about URI structure, implementations are free to use whatever form they wish.
109
+
JSON:API has no requirements about URI structure, implementations are free to use whatever form they wish.
0 commit comments