Skip to content

Commit 6c5d9ad

Browse files
committed
Use JSON:API instead of JSON API in the specification
1 parent 2ce21b3 commit 6c5d9ad

File tree

6 files changed

+116
-116
lines changed

6 files changed

+116
-116
lines changed

_format/1.0/index.md

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ version: 1.0
44

55
## <a href="#introduction" id="introduction" class="headerlink"></a> Introduction
66

7-
JSON API is a specification for how a client should request that resources be
7+
JSON:API is a specification for how a client should request that resources be
88
fetched or modified, and how a server should respond to those requests.
99

10-
JSON API is designed to minimize both the number of requests and the amount of
10+
JSON:API is designed to minimize both the number of requests and the amount of
1111
data transmitted between clients and servers. This efficiency is achieved
1212
without compromising readability, flexibility, or discoverability.
1313

14-
JSON API requires use of the JSON API media type
14+
JSON:API requires use of the JSON:API media type
1515
([`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json))
1616
for exchanging data.
1717

@@ -26,26 +26,26 @@ interpreted as described in RFC 2119
2626

2727
### <a href="#content-negotiation-clients" id="content-negotiation-clients" class="headerlink"></a> Client Responsibilities
2828

29-
Clients **MUST** send all JSON API data in request documents with the header
29+
Clients **MUST** send all JSON:API data in request documents with the header
3030
`Content-Type: application/vnd.api+json` without any media type parameters.
3131

32-
Clients that include the JSON API media type in their `Accept` header **MUST**
32+
Clients that include the JSON:API media type in their `Accept` header **MUST**
3333
specify the media type there at least once without any media type parameters.
3434

3535
Clients **MUST** ignore any parameters for the `application/vnd.api+json`
3636
media type received in the `Content-Type` header of response documents.
3737

3838
### <a href="#content-negotiation-servers" id="content-negotiation-servers" class="headerlink"></a> Server Responsibilities
3939

40-
Servers **MUST** send all JSON API data in response documents with the header
40+
Servers **MUST** send all JSON:API data in response documents with the header
4141
`Content-Type: application/vnd.api+json` without any media type parameters.
4242

4343
Servers **MUST** respond with a `415 Unsupported Media Type` status code if
4444
a request specifies the header `Content-Type: application/vnd.api+json`
4545
with any media type parameters.
4646

4747
Servers **MUST** respond with a `406 Not Acceptable` status code if a
48-
request's `Accept` header contains the JSON API media type and all instances
48+
request's `Accept` header contains the JSON:API media type and all instances
4949
of that media type are modified with media type parameters.
5050

5151
> Note: The content negotiation requirements exist to allow future versions
@@ -54,9 +54,9 @@ and versioning.
5454

5555
## <a href="#document-structure" id="document-structure" class="headerlink"></a> Document Structure
5656

57-
This section describes the structure of a JSON API document, which is identified
57+
This section describes the structure of a JSON:API document, which is identified
5858
by the media type [`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json).
59-
JSON API documents are defined in JavaScript Object Notation (JSON)
59+
JSON:API documents are defined in JavaScript Object Notation (JSON)
6060
[[RFC7159](http://tools.ietf.org/html/rfc7159)].
6161

6262
Although the same media type is used for both request and response documents,
@@ -72,7 +72,7 @@ changes.
7272

7373
### <a href="#document-top-level" id="document-top-level" class="headerlink"></a> Top Level
7474

75-
A JSON object **MUST** be at the root of every JSON API request and response
75+
A JSON object **MUST** be at the root of every JSON:API request and response
7676
containing data. This object defines a document's "top level".
7777

7878
A document **MUST** contain at least one of the following top-level members:
@@ -146,7 +146,7 @@ it only contains one item or is empty.
146146

147147
### <a href="#document-resource-objects" id="document-resource-objects" class="headerlink"></a> Resource Objects
148148

149-
"Resource objects" appear in a JSON API document to represent resources.
149+
"Resource objects" appear in a JSON:API document to represent resources.
150150

151151
A resource object **MUST** contain at least the following top-level members:
152152

@@ -160,7 +160,7 @@ In addition, a resource object **MAY** contain any of these top-level members:
160160

161161
* `attributes`: an [attributes object][attributes] representing some of the resource's data.
162162
* `relationships`: a [relationships object][relationships] describing relationships between
163-
the resource and other JSON API resources.
163+
the resource and other JSON:API resources.
164164
* `links`: a [links object][links] containing links related to the resource.
165165
* `meta`: a [meta object][meta] containing non-standard meta-information about a
166166
resource that can not be represented as an attribute or relationship.
@@ -397,7 +397,7 @@ A complete example document with multiple included relationships:
397397
"type": "articles",
398398
"id": "1",
399399
"attributes": {
400-
"title": "JSON API paints my bikeshed!"
400+
"title": "JSON:API paints my bikeshed!"
401401
},
402402
"links": {
403403
"self": "http://example.com/articles/1"
@@ -545,9 +545,9 @@ objects in the future. It is also possible that the allowed values of
545545
additional members will be expanded (e.g. a `collection` link may support an
546546
array of values, whereas a `self` link does not).
547547

548-
### <a href="#document-jsonapi-object" id="document-jsonapi-object" class="headerlink"></a> JSON API Object
548+
### <a href="#document-jsonapi-object" id="document-jsonapi-object" class="headerlink"></a> JSON:API Object
549549

550-
A JSON API document **MAY** include information about its implementation
550+
A JSON:API document **MAY** include information about its implementation
551551
under a top level `jsonapi` member. If present, the value of the `jsonapi`
552552
member **MUST** be an object (a "jsonapi object"). The jsonapi object **MAY**
553553
contain a `version` member whose value is a string indicating the highest JSON
@@ -565,12 +565,12 @@ value is a [meta] object that contains non-standard meta-information.
565565
If the `version` member is not present, clients should assume the server
566566
implements at least version 1.0 of the specification.
567567

568-
> Note: Because JSON API is committed to making additive changes only, the
568+
> Note: Because JSON:API is committed to making additive changes only, the
569569
version string primarily indicates which new features a server may support.
570570

571571
### <a href="#document-member-names" id="document-member-names" class="headerlink"></a> Member Names
572572

573-
All member names used in a JSON API document **MUST** be treated as case sensitive
573+
All member names used in a JSON:API document **MUST** be treated as case sensitive
574574
by clients and servers, and they **MUST** meet all of the following conditions:
575575

576576
- Member names **MUST** contain at least one character.
@@ -695,7 +695,7 @@ Content-Type: application/vnd.api+json
695695
"type": "articles",
696696
"id": "1",
697697
"attributes": {
698-
"title": "JSON API paints my bikeshed!"
698+
"title": "JSON:API paints my bikeshed!"
699699
}
700700
}, {
701701
"type": "articles",
@@ -747,7 +747,7 @@ Content-Type: application/vnd.api+json
747747
"type": "articles",
748748
"id": "1",
749749
"attributes": {
750-
"title": "JSON API paints my bikeshed!"
750+
"title": "JSON:API paints my bikeshed!"
751751
},
752752
"relationships": {
753753
"author": {
@@ -1099,12 +1099,12 @@ Keys **MUST** either be omitted or have a `null` value to indicate that a
10991099
particular link is unavailable.
11001100

11011101
Concepts of order, as expressed in the naming of pagination links, **MUST**
1102-
remain consistent with JSON API's [sorting rules](#fetching-sorting).
1102+
remain consistent with JSON:API's [sorting rules](#fetching-sorting).
11031103

11041104
The `page` query parameter is reserved for pagination. Servers and clients
11051105
**SHOULD** use this key for pagination operations.
11061106

1107-
> Note: JSON API is agnostic about the pagination strategy used by a server.
1107+
> Note: JSON:API is agnostic about the pagination strategy used by a server.
11081108
Effective pagination strategies include (but are not limited to):
11091109
page-based, offset-based, and cursor-based. The `page` query parameter can
11101110
be used as a basis for any of these strategies. For example, a page-based
@@ -1124,7 +1124,7 @@ collection as primary data, regardless of the request type.
11241124
The `filter` query parameter is reserved for filtering data. Servers and clients
11251125
**SHOULD** use this key for filtering operations.
11261126

1127-
> Note: JSON API is agnostic about the strategies supported by a server. The
1127+
> Note: JSON:API is agnostic about the strategies supported by a server. The
11281128
`filter` query parameter can be used as the basis for any number of filtering
11291129
strategies.
11301130

@@ -1137,7 +1137,7 @@ A request **MUST** completely succeed or fail (in a single "transaction"). No
11371137
partial updates are allowed.
11381138

11391139
> Note: The `type` member is required in every [resource object][resource objects] throughout requests and
1140-
responses in JSON API. There are some cases, such as when `POST`ing to an
1140+
responses in JSON:API. There are some cases, such as when `POST`ing to an
11411141
endpoint representing heterogenous data, when the `type` could not be inferred
11421142
from the endpoint. However, picking and choosing when it is required would be
11431143
confusing; it would be hard to remember when it was required and when it was
@@ -1495,7 +1495,7 @@ responses, in accordance with
14951495
### <a href="#crud-updating-relationships" id="crud-updating-relationships" class="headerlink"></a> Updating Relationships
14961496

14971497
Although relationships can be modified along with resources (as described
1498-
above), JSON API also supports updating of relationships independently at
1498+
above), JSON:API also supports updating of relationships independently at
14991499
URLs from [relationship links][relationships].
15001500

15011501
> Note: Relationships are updated without exposing the underlying server
@@ -1505,7 +1505,7 @@ has many authors, it is possible to remove one of the authors from the article
15051505
without deleting the person itself. Similarly, if an article has many tags, it
15061506
is possible to add or remove tags. Under the hood on the server, the first
15071507
of these examples might be implemented with a foreign key, while the second
1508-
could be implemented with a join table, but the JSON API protocol would be
1508+
could be implemented with a join table, but the JSON:API protocol would be
15091509
the same in both cases.
15101510

15111511
> Note: A server may choose to delete the underlying resource if a
@@ -1650,7 +1650,7 @@ Accept: application/vnd.api+json
16501650

16511651
> Note: RFC 7231 specifies that a DELETE request may include a body, but
16521652
that a server may reject the request. This spec defines the semantics of a
1653-
server, and we are defining its semantics for JSON API.
1653+
server, and we are defining its semantics for JSON:API.
16541654

16551655
#### <a href="#crud-updating-relationship-responses" id="crud-updating-relationship-responses" class="headerlink"></a> Responses
16561656

@@ -1754,7 +1754,7 @@ If a server encounters a query parameter that does not follow the naming
17541754
conventions above, and the server does not know how to process it as a query
17551755
parameter from this specification, it **MUST** return `400 Bad Request`.
17561756

1757-
> Note: This is to preserve the ability of JSON API to make additive additions
1757+
> Note: This is to preserve the ability of JSON:API to make additive additions
17581758
to standard query parameters without conflicting with existing implementations.
17591759

17601760
## <a href="#errors" id="errors" class="headerlink"></a> Errors
@@ -1775,7 +1775,7 @@ or `500 Internal Server Error` might be appropriate for multiple 5xx errors.
17751775

17761776
Error objects provide additional information about problems encountered while
17771777
performing an operation. Error objects **MUST** be returned as an array
1778-
keyed by `errors` in the top level of a JSON API document.
1778+
keyed by `errors` in the top level of a JSON:API document.
17791779

17801780
An error object **MAY** have the following members:
17811781

_format/1.0/normative-statements.json

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ layout: null
294294
"type": "normative-statements",
295295
"attributes": {
296296
"level": "MUST",
297-
"description": "Clients **MUST** send all JSON API data in request documents with the header `Content-Type: application/vnd.api+json` without any media type parameters."
297+
"description": "Clients **MUST** send all JSON:API data in request documents with the header `Content-Type: application/vnd.api+json` without any media type parameters."
298298
},
299299
"relationships": {
300300
"section": {
@@ -307,7 +307,7 @@ layout: null
307307
"type": "normative-statements",
308308
"attributes": {
309309
"level": "MUST",
310-
"description": "Clients that include the JSON API media type in their `Accept` header **MUST** specify the media type there at least once without any media type parameters."
310+
"description": "Clients that include the JSON:API media type in their `Accept` header **MUST** specify the media type there at least once without any media type parameters."
311311
},
312312
"relationships": {
313313
"section": {
@@ -333,7 +333,7 @@ layout: null
333333
"type": "normative-statements",
334334
"attributes": {
335335
"level": "MUST",
336-
"description": "Servers **MUST** send all JSON API data in response documents with the header `Content-Type: application/vnd.api+json` without any media type parameters."
336+
"description": "Servers **MUST** send all JSON:API data in response documents with the header `Content-Type: application/vnd.api+json` without any media type parameters."
337337
},
338338
"relationships": {
339339
"section": {
@@ -359,7 +359,7 @@ layout: null
359359
"type": "normative-statements",
360360
"attributes": {
361361
"level": "MUST",
362-
"description": "Servers **MUST** respond with a `406 Not Acceptable` status code if a request's `Accept` header contains the JSON API media type and all instances of that media type are modified with media type parameters."
362+
"description": "Servers **MUST** respond with a `406 Not Acceptable` status code if a request's `Accept` header contains the JSON:API media type and all instances of that media type are modified with media type parameters."
363363
},
364364
"relationships": {
365365
"section": {
@@ -398,7 +398,7 @@ layout: null
398398
"type": "normative-statements",
399399
"attributes": {
400400
"level": "MUST",
401-
"description": "A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document's \"top level\"."
401+
"description": "A JSON object MUST be at the root of every JSON:API request and response containing data. This object defines a document's \"top level\"."
402402
},
403403
"relationships": {
404404
"section": {
@@ -515,7 +515,7 @@ layout: null
515515
"type": "normative-statements",
516516
"attributes": {
517517
"level": "MUST",
518-
"description": "In addition, a resource object MAY contain any of these top-level members:\\n\\n- `attributes`: an attributes object representing some of the resource's data.\\n- `relationships`: a relationships object describing relationships between the resource and other JSON API resources.\\n -`links`: a links object containing links related to the resource.\\n- `meta`: a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
518+
"description": "In addition, a resource object MAY contain any of these top-level members:\\n\\n- `attributes`: an attributes object representing some of the resource's data.\\n- `relationships`: a relationships object describing relationships between the resource and other JSON:API resources.\\n -`links`: a links object containing links related to the resource.\\n- `meta`: a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
519519
},
520520
"relationships": {
521521
"section": {
@@ -866,7 +866,7 @@ layout: null
866866
"type": "normative-statements",
867867
"attributes": {
868868
"level": "MAY",
869-
"description": "A JSON API document **MAY** include information about its implementation under a top level `jsonapi` member."
869+
"description": "A JSON:API document **MAY** include information about its implementation under a top level `jsonapi` member."
870870
},
871871
"relationships": {
872872
"section": {
@@ -892,7 +892,7 @@ layout: null
892892
"type": "normative-statements",
893893
"attributes": {
894894
"level": "MAY",
895-
"description": "The jsonapi object **MAY** contain a `version` member whose value is a string indicating the highest JSON API version supported."
895+
"description": "The jsonapi object **MAY** contain a `version` member whose value is a string indicating the highest JSON:API version supported."
896896
},
897897
"relationships": {
898898
"section": {
@@ -918,7 +918,7 @@ layout: null
918918
"type": "normative-statements",
919919
"attributes": {
920920
"level": "MUST",
921-
"description": "All member names used in a JSON API document **MUST** be treated as case sensitive by clients and servers"
921+
"description": "All member names used in a JSON:API document **MUST** be treated as case sensitive by clients and servers"
922922
},
923923
"relationships": {
924924
"section": {
@@ -1516,7 +1516,7 @@ layout: null
15161516
"type": "normative-statements",
15171517
"attributes": {
15181518
"level": "MUST",
1519-
"description": "Concepts of order, as expressed in the naming of pagination links, **MUST** remain consistent with JSON API's sorting rules."
1519+
"description": "Concepts of order, as expressed in the naming of pagination links, **MUST** remain consistent with JSON:API's sorting rules."
15201520
},
15211521
"relationships": {
15221522
"section": {
@@ -2660,7 +2660,7 @@ layout: null
26602660
"type": "normative-statements",
26612661
"attributes": {
26622662
"level": "MUST",
2663-
"description": "Error objects **MUST** be returned as an array keyed by `errors` in the top level of a JSON API document."
2663+
"description": "Error objects **MUST** be returned as an array keyed by `errors` in the top level of a JSON:API document."
26642664
},
26652665
"relationships": {
26662666
"section": {

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy