-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft.openapi-3.0.0-jsonapi-1.1.yaml
2885 lines (2406 loc) · 154 KB
/
draft.openapi-3.0.0-jsonapi-1.1.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.0
info:
title: 'OpenAPI 3.0.0 Specification for JSON:API v1.1'
version: 0.0.1
description: '[OpenAPI 3.0.0](https://spec.openapis.org/oas/v3.0.0) Specification for [JSON:API v1.1](https://jsonapi.org/format/1.1/)'
contact:
name: Leon(id) Komarovsky
email: [email protected]
tags:
- name: Collections
- name: Relationships
- name: Resources
servers:
- url: 'http://127.0.0.1:3100'
description: Mock Server
paths:
'/{collection}':
parameters:
- $ref: '#/components/parameters/collection'
get:
summary: Fetch Collection
operationId: getCollection
tags:
- Collections
description: Fetch collection of resources.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/filter'
requestBody:
description: |-
### 8.1 Fetching Resources
A server **MUST** support fetching resource data for every URL provided as:
- a `self` link as part of the top-level links object
- a `self` link as part of a resource-level links object
- a `related` link as part of a relationship-level links object
The following request fetches a collection of articles:
```http
GET /articles HTTP/1.1
Accept: application/vnd.api+json
```
JSON:API v1.1 spec: [8.1 Fetching Resources](https://jsonapi.org/format/1.1/#fetching-resources)
content:
application/vnd.api+json:
schema:
type: object
responses:
'200':
description: |-
### 8.1.1.1 200 OK
A server **MUST** respond to a successful request to fetch an individual resource or resource collection with a `200 OK` response.
A server **MUST** respond to a successful request to fetch a resource collection with an array of [resource objects](https://jsonapi.org/format/1.1/#document-resource-objects) or an empty array (`[]`) as the response document’s primary data.
For example, a GET request to a collection of articles could return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/articles"
},
"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON:API paints my bikeshed!"
}
}, {
"type": "articles",
"id": "2",
"attributes": {
"title": "Rails is Omakase"
}
}]
}
```
A similar response representing an empty collection would be:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/articles"
},
"data": []
}
```
JSON:API v1.1 spec: [8.1.1.1 200 OK](https://jsonapi.org/format/1.1/#fetching-resources-responses-200)
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/successDocument'
examples:
articlesCollection:
value:
links:
self: 'http://example.com/articles'
data:
- type: articles
id: '1'
attributes:
title: 'JSON:API paints my bikeshed!'
- type: articles
id: '2'
attributes:
title: Rails is Omakase
emptyCollection:
value:
data: []
links:
self: 'http://example.com/articles'
default:
description: |-
### 8.1.1.3 Other Responses
A server **MAY** respond with other HTTP status codes.
A server **MAY** include error details with [error responses](https://jsonapi.org/format/1.1/#errors).
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [8.1.1.3 Other Responses](https://jsonapi.org/format/1.1/#fetching-resources-responses-other)
post:
summary: Create Resource
operationId: createResource
tags:
- Resources
description: Create a new resource.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
requestBody:
description: |
### 9.1 Creating Resources
A resource can be created by sending a `POST` request to a URL that represents a collection of resources. The request **MUST** include a single [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) as primary data. The [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) **MUST** contain at least a `type` member.
For instance, a new photo might be created with the following request:
```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "photos",
"attributes": {
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
},
"relationships": {
"photographer": {
"data": { "type": "people", "id": "9" }
}
}
}
}
```
If a relationship is provided in the `relationships` member of the [resource object](https://jsonapi.org/format/1.1/#document-resource-objects), its value **MUST** be a relationship object with a `data` member. The value of this key represents the [linkage](https://jsonapi.org/format/1.1/#document-resource-object-linkage) the new resource is to have.
JSON:API v1.1 spec: [9.1 Creating Resources](https://jsonapi.org/format/1.1/#crud-creating)
### 9.1.1 Client-Generated IDs
A server **MAY** accept a client-generated ID along with a request to create a resource. An ID **MUST** be specified with an `id` key, the value of which **MUST** be a universally unique identifier. The client **SHOULD** use a properly generated and formatted *UUID* as described in RFC 4122 [[RFC4122](http://tools.ietf.org/html/rfc4122.html)].
> NOTE: In some use-cases, such as importing data from another source, it may be possible to use something other than a UUID that is still guaranteed to be globally unique. Do not use anything other than a UUID unless you are 100% confident that the strategy you are using indeed generates globally unique identifiers.
For example:
```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "photos",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
}
}
}
```
A server **MUST** return `403 Forbidden` in response to an unsupported request to create a resource with a client-generated ID.
JSON:API v1.1 spec: [9.1.1 Client-Generated IDs](https://jsonapi.org/format/1.1/#crud-creating-client-ids)
content:
application/vnd.api+json:
schema:
type: object
examples:
createPhoto:
value:
data:
type: photos
attributes:
title: Ember Hamster
src: 'http://example.com/images/productivity.png'
relationships:
photographer:
data:
type: people
id: '9'
createPhotoWithClientGeneratedId:
value:
data:
type: photos
id: 550e8400-e29b-41d4-a716-446655440000
attributes:
title: Ember Hamster
src: 'http://example.com/images/productivity.png'
responses:
'201':
description: |-
### 9.1.2.1 201 Created
If the requested resource has been created successfully and the server changes the resource in any way (for example, by assigning an `id`), the server **MUST** return a `201 Created` response and a document that contains the resource as primary data.
The response **SHOULD** include a `Location` header identifying the location of the newly created resource, in order to comply with [RFC 7231](http://tools.ietf.org/html/rfc7231#section-6.3.2).
If the [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) returned by the response contains a `self` key in its `links` member and a `Location` header is provided, the value of the `self` member **MUST** match the value of the `Location` header.
```http
HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json
{
"data": {
"type": "photos",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
},
"links": {
"self": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000"
}
}
}
```
A server **MAY** return a `201 Created` response with a document that contains no primary data if the requested resource has been created successfully and the server does not change the resource in any way (for example, by assigning an `id` or `createdAt` attribute). Other top-level members, such as [meta](https://jsonapi.org/format/1.1/#document-meta), could be included in the response document.
> Note: Only servers that accept [Client-Generated IDs](https://jsonapi.org/format/1.1/#crud-creating-client-ids) can avoid assigning an `id` to a new resource.
JSON:API v1.1 spec: [9.1.2.1 201 Created](https://jsonapi.org/format/1.1/#crud-creating-responses-201)
content:
application/vnd.api+json:
schema:
type: object
examples:
createPhoto:
value:
data:
type: photos
id: 550e8400-e29b-41d4-a716-446655440000
attributes:
title: Ember Hamster
src: 'http://example.com/images/productivity.png'
links:
self: 'http://example.com/photos/550e8400-e29b-41d4-a716-446655440000'
'202':
description: |-
### 9.1.2.2 202 Accepted
If a request to create a resource has been accepted for processing, but the processing has not been completed by the time the server responds, the server **MUST** return a `202 Accepted` status code.
JSON:API v1.1 spec: [9.1.2.2 202 Accepted](https://jsonapi.org/format/1.1/#crud-creating-responses-202)
'204':
description: |-
### 9.1.2.3 204 No Content
If the requested resource has been created successfully and the server does not change the resource in any way (for example, by assigning an `id` or `createdAt` attribute), the server **MUST** return either a `201 Created` status code and response document or a `204 No Content` status code with no response document.
JSON:API v1.1 spec: [9.1.2.3 204 No Content](https://jsonapi.org/format/1.1/#crud-creating-responses-204)
'403':
description: |-
### 9.1.1 Client-Generated IDs
A server **MUST** return `403 Forbidden` in response to an unsupported request to create a resource with a client-generated ID.
JSON:API v1.1 spec: [9.1.1 Client-Generated IDs](https://jsonapi.org/format/1.1/#crud-creating-client-ids)
### 9.1.2.4 403 Forbidden
A server **MAY** return `403 Forbidden` in response to an unsupported request to create a resource.
JSON:API v1.1 spec: [9.1.2.4 403 Forbidden](https://jsonapi.org/format/1.1/#crud-creating-responses-403)
'404':
description: |-
### 9.1.2.5 404 Not Found
A server **MUST** return `404 Not Found` when processing a request that references a related resource that does not exist.
JSON:API v1.1 spec: [9.1.2.5 404 Not Found](https://jsonapi.org/format/1.1/#crud-creating-responses-404)
'406':
description: |-
### 9.1.2.6 406 Conflict
A server **MUST** return `409 Conflict` when processing a `POST` request to create a resource with a client-generated ID that already exists.
A server **MUST** return `409 Conflict` when processing a `POST` request in which the [resource object](https://jsonapi.org/format/1.1/#document-resource-objects)’s `type` is not among the type(s) that constitute the collection represented by the endpoint.
A server **SHOULD** include error details and provide enough information to recognize the source of the conflict.
JSON:API v1.1 spec: [9.1.2.6 406 Conflict](https://jsonapi.org/format/1.1/#crud-creating-responses-406)
default:
description: |-
### 9.1.2.7 Other Responses
A server **MAY** respond with other HTTP status codes.
A server **MAY** include [error details](https://jsonapi.org/format/1.1/#errors) with error responses.
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [9.1.2.7 Other Responses](https://jsonapi.org/format/1.1/#crud-creating-responses-other)
'/{collection}/{id}':
parameters:
- $ref: '#/components/parameters/collection'
- $ref: '#/components/parameters/id'
get:
summary: Fetch Resource
operationId: getResource
tags:
- Resources
description: Fetch individual resource.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
requestBody:
description: |
### 8.1 Fetching Resources
A server **MUST** support fetching resource data for every URL provided as:
- a `self` link as part of the top-level links object
- a `self` link as part of a resource-level links object
- a `related` link as part of a relationship-level links object
The following request fetches an article:
```http
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json
```
JSON:API v1.1 spec: [8.1 Fetching Resources](https://jsonapi.org/format/1.1/#fetching-resources)
content:
application/vnd.api+json:
schema:
type: object
responses:
'200':
description: |-
### 8.1.1.1 200 OK
A server **MUST** respond to a successful request to fetch an individual resource or resource collection with a `200 OK` response.
A server **MUST** respond to a successful request to fetch an individual resource with a [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) or `null` provided as the response document’s primary data.
`null` is only an appropriate response when the requested URL is one that might correspond to a single resource, but doesn’t currently.
> Note: Consider, for example, a request to fetch a to-one related resource link. This request would respond with `null` when the relationship is empty (such that the link is corresponding to no resources) but with the single related resource’s [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) otherwise.
For example, a `GET` request to an individual article could return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "http://example.com/articles/1"
},
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON:API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"related": "http://example.com/articles/1/author"
}
}
}
}
}
```
JSON:API v1.1 spec: [8.1.1.1 200 OK](https://jsonapi.org/format/1.1/#fetching-resources-responses-200)
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/successDocument'
examples:
article:
value:
data:
type: articles
id: '1'
attributes:
title: 'JSON:API paints my bikeshed!'
relationships:
author:
links:
related: 'http://example.com/articles/1/author'
links:
self: 'http://example.com/articles/1'
'404':
description: |-
### 8.1.1.2 404 Not Found
A server **MUST** respond with `404 Not Found` when processing a request to fetch a single resource that does not exist, except when the request warrants a `200 OK` response with `null` as the primary data.
JSON:API v1.1 spec: [8.1.1.2 404 Not Found](https://jsonapi.org/format/1.1/#fetching-resources-responses-404)
default:
description: |-
### 8.1.1.3 Other Responses
A server **MAY** respond with other HTTP status codes.
A server **MAY** include error details with [error responses](https://jsonapi.org/format/1.1/#errors).
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [8.1.1.3 Other Responses](https://jsonapi.org/format/1.1/#fetching-resources-responses-other)
patch:
summary: Update Resource
operationId: updateResource
tags:
- Resources
description: Update individual resource.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
requestBody:
description: |-
### 9.2 Updating Resources
A resource can be updated by sending a `PATCH` request to the URL that represents the resource.
The URL for a resource can be obtained in the `self` link of the [resource object](https://jsonapi.org/format/1.1/#document-resource-objects). Alternatively, when a `GET` request returns a single [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) as primary data, the same request URL can be used for updates.
The `PATCH` request **MUST** include a single [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) as primary data. The [resource object](https://jsonapi.org/format/1.1/#document-resource-objects) **MUST** contain `type` and `id` members.
For example:
```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "To TDD or Not"
}
}
}
```
JSON:API v1.1 spec: [9.2 Updating Resources](https://jsonapi.org/format/1.1/#crud-updating)
### 9.2.1 Updating a Resource’s Attributes
Any or all of a resource’s [attributes](https://jsonapi.org/format/1.1/#document-resource-object-attributes) **MAY** be included in the resource object included in a `PATCH` request.
If a request does not include all of the [attributes](https://jsonapi.org/format/1.1/#document-resource-object-attributes) for a resource, the server **MUST** interpret the missing attributes as if they were included with their current values. The server **MUST NOT** interpret missing attributes as `null` values.
For example, the following `PATCH` request is interpreted as a request to update only the `title` and `text` attributes of an article:
```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "To TDD or Not",
"text": "TLDR; It's complicated... but check your test coverage regardless."
}
}
}
```
JSON:API v1.1 spec: [9.2.1 Updating Resource’s Attributes](https://jsonapi.org/format/1.1/#crud-updating-resource-attributes)
### 9.2.2 Updating a Resource’s Relationships
Any or all of a resource’s [relationships](https://jsonapi.org/format/1.1/#document-resource-object-relationships) **MAY** be included in the resource object included in a `PATCH` request.
If a request does not include all of the [relationships](https://jsonapi.org/format/1.1/#document-resource-object-relationships) for a resource, the server **MUST** interpret the missing [relationships](https://jsonapi.org/format/1.1/#document-resource-object-relationships) as if they were included with their current values. It **MUST NOT** interpret them as `null` or empty values.
If a relationship is provided in the `relationships` member of a resource object in a `PATCH` request, its value **MUST** be a relationship object with a `data` member. The relationship’s value will be replaced with the value specified in this member.
For instance, the following `PATCH` request will update the `author` relationship of an article:
```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "articles",
"id": "1",
"relationships": {
"author": {
"data": { "type": "people", "id": "1" }
}
}
}
}
```
Likewise, the following `PATCH` request performs a complete replacement of the `tags` for an article:
```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "articles",
"id": "1",
"relationships": {
"tags": {
"data": [
{ "type": "tags", "id": "2" },
{ "type": "tags", "id": "3" }
]
}
}
}
}
```
A server **MAY** reject an attempt to do a full replacement of a to-many relationship. In such a case, the server **MUST** reject the entire update, and return a `403 Forbidden` response.
> Note: Since full replacement may be a very dangerous operation, a server may choose to disallow it. For example, a server may reject full replacement if it has not provided the client with the full list of associated objects, and does not want to allow deletion of records the client has not seen.
JSON:API v1.1 spec: [9.2.2 Updating Resource’s Relationships](https://jsonapi.org/format/1.1/#crud-updating-resource-relationships)
content:
application/vnd.api+json:
schema:
type: object
examples:
updateArticle:
value:
data:
type: articles
id: '1'
attributes:
title: To TDD or Not
updateAttributes:
value:
data:
type: articles
id: '1'
attributes:
title: To TDD or Not
text: TLDR; It's complicated... but check your test coverage regardless.
updateRelationshipsAuthor:
value:
data:
type: articles
id: '1'
relationships:
author:
data:
type: people
id: '1'
updateRelationshipsReplaceTags:
value:
data:
type: articles
id: '1'
relationships:
tags:
data:
- type: tags
id: '2'
- type: tags
id: '3'
responses:
'200':
description: |-
### 9.2.3.1 200 OK
If a server accepts an update but also changes the targeted resource in ways other than those specified by the request (for example, updating the `updatedAt` attribute or a computed `sha`), it **MUST** return a `200 OK` response and a document that contains the updated resource as primary data.
A server **MAY** return a `200 OK` response with a document that contains no primary data if an update is successful and the server does not change the targeted resource in ways other than those specified by the request. Other top-level members, such as [meta](https://jsonapi.org/format/1.1/#document-meta), could be included in the response document.
JSON:API v1.1 spec: [9.2.3.1 200 OK](https://jsonapi.org/format/1.1/#crud-updating-responses-200)
'202':
description: |-
### 9.2.3.2 202 Accepted
If an update request has been accepted for processing, but the processing has not been completed by the time the server responds, the server **MUST** return a `202 Accepted` status code.
JSON:API v1.1 spec: [9.2.3.2 202 Accepted](https://jsonapi.org/format/1.1/#crud-updating-responses-202)
'204':
description: |-
### 9.2.3.3 204 No Content
If an update is successful and the server doesn’t change the targeted resource in ways other than those specified by the request, the server **MUST** return either a `200 OK` status code and response document or a `204 No Content` status code with no response document.
JSON:API v1.1 spec: [9.2.3.3 204 No Content](https://jsonapi.org/format/1.1/#crud-updating-responses-204)
'403':
description: |-
### 9.2.3.4 403 Forbidden
A server **MUST** return `403 Forbidden` in response to an unsupported request to update a resource or relationship.
JSON:API v1.1 spec: [9.2.3.4 403 Forbidden](https://jsonapi.org/format/1.1/#crud-updating-responses-403)
'404':
description: |-
### 9.2.3.5 404 Not Found
A server **MUST** return `404 Not Found` when processing a request to modify a resource that does not exist.
A server **MUST** return `404 Not Found` when processing a request that references a related resource that does not exist.
JSON:API v1.1 spec: [9.2.3.5 404 Not Found](https://jsonapi.org/format/1.1/#crud-updating-responses-404)
'409':
description: |-
### 9.2.3.6 409 Conflict
A server **MAY** return `409 Conflict` when processing a `PATCH` request to update a resource if that update would violate other server-enforced constraints (such as a uniqueness constraint on a property other than `id`).
A server **MUST** return `409 Conflict` when processing a `PATCH` request in which the resource object’s `type` or `id` do not match the server’s endpoint.
A server **SHOULD** include error details and provide enough information to recognize the source of the conflict.
JSON:API v1.1 spec: [9.2.3.6 409 Conflict](https://jsonapi.org/format/1.1/#crud-updating-responses-409)
default:
description: |-
### 9.2.3.7 Other Responses
A server **MAY** respond with other HTTP status codes.
A server **MAY** include [error details](https://jsonapi.org/format/1.1/#errors) with error responses.
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [9.2.3.7 Other Responses](https://jsonapi.org/format/1.1/#crud-updating-responses-other)
delete:
summary: Delete Resource
operationId: deleteResource
tags:
- Resources
description: Delete individual resource.
requestBody:
description: |-
### 9.4 Deleting Resources
A resource can be deleted by sending a `DELETE` request to the URL that represents the resource:
```http
DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json
```
JSON:API v1.1 spec: [9.4 Deleting Resources](https://jsonapi.org/format/1.1/#crud-deleting)
content:
application/vnd.api+json:
schema:
type: object
responses:
'200':
description: |-
### 9.4.1.1 200 OK
A server **MAY** return a `200 OK` response with a document that contains no primary data if a deletion request is successful. Other top-level members, such as [meta](https://jsonapi.org/format/1.1/#document-meta), could be included in the response document.
JSON:API v1.1 spec: [9.4.1.1 200 OK](https://jsonapi.org/format/1.1/#crud-deleting-responses-200)
'202':
description: |-
### 9.4.1.2 202 Accepted
If a deletion request has been accepted for processing, but the processing has not been completed by the time the server responds, the server **MUST** return a `202 Accepted` status code.
JSON:API v1.1 spec: [9.4.1.2 202 Accepted](https://jsonapi.org/format/1.1/#crud-deleting-responses-202)
'204':
description: |-
### 9.4.1.3 204 No Content
If a deletion request is successful, the server **MUST** return either a `200 OK` status code and response document or a `204 No Content` status code with no response document.
JSON:API v1.1 spec: [9.4.1.3 204 No Content](https://jsonapi.org/format/1.1/#crud-deleting-responses-204)
'404':
description: |-
### 9.4.1.4 404 Not Found
A server **SHOULD** return a `404 Not Found` status code if a deletion request fails due to the resource not existing.
JSON:API v1.1 spec: [9.4.1.4 404 Not Found](https://jsonapi.org/format/1.1/#crud-deleting-responses-404)
default:
description: |-
### 9.4.1.5 Other Responses
A server **MAY** respond with other HTTP status codes.
A server **MAY** include [error details](https://jsonapi.org/format/1.1/#errors) with error responses.
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [9.4.1.5 Other Responses](https://jsonapi.org/format/1.1/#crud-deleting-responses-other)
'/{collection}/{id}/relationships/{relationship}':
get:
summary: Fetch Resource Relationships
operationId: getResourceRelationships
tags:
- Relationships
description: Fetch resource relationships.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
requestBody:
description: |-
### 8.2 Fetching Relationships
A server **MUST** support fetching relationship data for every relationship URL provided as a `self` link as part of a relationship’s `links` object.
For example, the following request fetches data about an article’s comments:
```http
GET /articles/1/relationships/comments HTTP/1.1
Accept: application/vnd.api+json
```
And the following request fetches data about an article’s author:
```http
GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json
```
JSON:API v1.1 spec: [8.2 Fetching Relationships](https://jsonapi.org/format/1.1/#fetching-relationships)
content:
application/vnd.api+json:
schema:
type: object
responses:
'200':
description: |-
A server **MUST** respond to a successful request to fetch a relationship with a `200 OK` response.
The primary data in the response document **MUST** match the appropriate value for [resource linkage](https://jsonapi.org/format/1.1/#document-resource-object-linkage), as described in [relationship objects](https://jsonapi.org/format/1.1/#document-resource-object-relationships).
The top-level [links object](https://jsonapi.org/format/1.1/#document-links) **MAY** contain `self` and `related` links, as described in
[relationship objects](https://jsonapi.org/format/1.1/#document-resource-object-relationships).
For example, a `GET` request to a URL from a to-one relationship link could return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "/articles/1/relationships/author",
"related": "/articles/1/author"
},
"data": {
"type": "people",
"id": "12"
}
}
```
If the above relationship is empty, then a `GET` request to the same URL would return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "/articles/1/relationships/author",
"related": "/articles/1/author"
},
"data": null
}
```
A `GET` request to a URL from a to-many relationship link could return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "/articles/1/relationships/tags",
"related": "/articles/1/tags"
},
"data": [
{ "type": "tags", "id": "2" },
{ "type": "tags", "id": "3" }
]
}
```
If the above relationship is empty, then a GET request to the same URL would return:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"links": {
"self": "/articles/1/relationships/tags",
"related": "/articles/1/tags"
},
"data": []
}
```
JSON:API v1.1 spec: [8.2.1.1 200 OK](https://jsonapi.org/format/1.1/#fetching-relationships-responses-200)
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/successDocument'
examples:
toOne:
value:
data:
type: people
id: '12'
links:
self: /articles/1/relationships/author
related: /articles/1/author
toOneEmpty:
value:
data: null
links:
self: /articles/1/relationships/author
related: /articles/1/author
toMany:
value:
data:
- type: tags
id: '2'
- type: tags
id: '3'
links:
self: /articles/1/relationships/tags
related: /articles/1/tags
toManyEmpty:
value:
data: []
links:
self: /articles/1/relationships/tags
related: /articles/1/tags
'404':
description: |-
A server **MUST** return `404 Not Found` when processing a request to fetch a relationship link URL that does not exist.
> Note: This can happen when the parent resource of the relationship does not exist. For example, when `/articles/1` does not exist, request to `/articles/1/relationships/tags` returns `404 Not Found`.
If a relationship link URL exists but the relationship is empty, then `200 OK` **MUST** be returned, as described above.
JSON:API v1.1 spec: [8.2.1.2 404 Not Found](https://jsonapi.org/format/1.1/#fetching-relationships-responses-404)
default:
description: |-
A server **MAY** respond with other HTTP status codes.
A server **MAY** include error details with [error responses](https://jsonapi.org/format/1.1/#errors).
A server **MUST** prepare responses, and a client **MUST** interpret responses, in accordance with [HTTP semantics](http://tools.ietf.org/html/rfc7231).
JSON:API v1.1 spec: [8.2.1.3 Other Responses](https://jsonapi.org/format/1.1/#fetching-relationships-responses-other)
parameters:
- $ref: '#/components/parameters/collection'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/relationship'
patch:
summary: Replace Resource Relationships
operationId: updateResourceRelationships
tags:
- Relationships
description: Replace Resource Relationships.
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/fields'
requestBody:
description: |-
### 9.3 Updating Relationships
Although relationships can be modified along with resources, JSON:API also supports updating of relationships independently at URLs from relationship links.
> Note: Relationships are updated without exposing the underlying server semantics, such as foreign keys. Furthermore, relationships can be updated without necessarily affecting the related resources. For example, if an article has many authors, it is possible to remove one of the authors from the article without deleting the person itself. Similarly, if an article has many tags, it is possible to add or remove tags. Under the hood on the server, the first of these examples might be implemented with a foreign key, while the second could be implemented with a join table, but the JSON:API protocol would be the same in both cases.
> Note: A server may choose to delete the underlying resource if a relationship is deleted (as a garbage collection measure).
JSON:API v1.1 spec: [9.3 Updating Relationships](https://jsonapi.org/format/1.1/#crud-updating-relationships)
### 9.3.1 Updating To-One Relationships
A to-one relationship can be updated by sending a `PATCH` request to a URL from a to-one [relationship link](https://jsonapi.org/format/1.1/#document-resource-object-relationships).
The `PATCH` request **MUST** include a top-level member named `data` containing one of:
- a [resource identifier object](https://jsonapi.org/format/1.1/#document-resource-identifier-objects) corresponding to the new related resource.
- `null`, to remove the relationship.
For example, the following request updates the author of an article:
```http
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": { "type": "people", "id": "12" }
}
```
And the following request clears the author of the same article:
```http
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": null
}
```
If the relationship is updated successfully then the server **MUST** return a successful response.
JSON:API v1.1 spec: [9.3.1 Updating To-One Relationships](https://jsonapi.org/format/1.1/#crud-updating-to-one-relationships)
### 9.3.2 Updating To-Many Relationships
A to-many relationship can be updated by sending a `PATCH`, `POST`, or `DELETE` request to a URL from a to-many [relationship link](https://jsonapi.org/format/1.1/#document-resource-object-relationships).
For all request types, the body **MUST** contain a `data` member whose value is an empty array or an array of [resource identifier objects](https://jsonapi.org/format/1.1/#document-resource-identifier-objects).
If a client makes a `PATCH` request to a URL from a to-many [relationship link](https://jsonapi.org/format/1.1/#document-resource-object-relationships), the server **MUST** either completely replace every member of the relationship, return an appropriate error response if some resources cannot be found or accessed, or return a `403 Forbidden` response if complete replacement is not allowed by the server.
For example, the following request replaces every tag for an article:
```http
PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": [
{ "type": "tags", "id": "2" },
{ "type": "tags", "id": "3" }
]
}
```
And the following request clears every tag for an article:
```http
PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": []
}
```
JSON:API v1.1 spec: [9.3.2 Updating To-Many Relationships](https://jsonapi.org/format/1.1/#crud-updating-to-many-relationships)
content:
application/vnd.api+json:
schema:
type: object
examples:
updateToOneAuthor:
value:
data:
type: people
id: '12'
clearToOneAuthor:
value:
data: null
replaceToManyTags:
value:
data:
- type: tags