Skip to content

Commit 8e46750

Browse files
author
Bart Koelman
committed
Added documentation
1 parent 0e29b4f commit 8e46750

File tree

13 files changed

+237
-15
lines changed

13 files changed

+237
-15
lines changed

‎docs/internals/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Internals
22

3-
The section contains overviews for the inner workings of the JsonApiDotNetCore library.
3+
This section contains overviews for the inner workings of the JsonApiDotNetCore library.

‎docs/request-examples/index.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -45,22 +45,22 @@ _Note that cURL requires "[" and "]" in URLs to be escaped._
4545

4646
# Writing data
4747

48-
### Create
48+
### Create resource
4949

5050
[!code-ps[REQUEST](010_CREATE_Person.ps1)]
5151
[!code-json[RESPONSE](010_CREATE_Person_Response.json)]
5252

53-
### Create with relationship
53+
### Create resource with relationship
5454

5555
[!code-ps[REQUEST](011_CREATE_Book-with-Author.ps1)]
5656
[!code-json[RESPONSE](011_CREATE_Book-with-Author_Response.json)]
5757

58-
### Update
58+
### Update resource
5959

6060
[!code-ps[REQUEST](012_PATCH_Book.ps1)]
6161
[!code-json[RESPONSE](012_PATCH_Book_Response.json)]
6262

63-
### Delete
63+
### Delete resource
6464

6565
[!code-ps[REQUEST](013_DELETE_Book.ps1)]
6666
[!code-json[RESPONSE](013_DELETE_Book_Response.json)]

‎docs/usage/filtering.md renamed to ‎docs/usage/reading/filtering.md

File renamed without changes.

‎docs/usage/including-relationships.md renamed to ‎docs/usage/reading/including-relationships.md

File renamed without changes.

‎docs/usage/pagination.md renamed to ‎docs/usage/reading/pagination.md

File renamed without changes.

‎docs/usage/sorting.md renamed to ‎docs/usage/reading/sorting.md

File renamed without changes.

‎docs/usage/sparse-fieldset-selection.md renamed to ‎docs/usage/reading/sparse-fieldset-selection.md

File renamed without changes.

‎docs/usage/resources/relationships.md

-3
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,6 @@ public class TodoItem : Identifiable<int>
2020
}
2121
```
2222

23-
The convention used to locate the foreign key property (e.g. `OwnerId`) can be changed on
24-
the @JsonApiDotNetCore.Configuration.JsonApiOptions#JsonApiDotNetCore_Configuration_JsonApiOptions_RelatedIdMapper
25-
2623
## HasMany
2724

2825
```c#

‎docs/usage/toc.md

+12-5
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,20 @@
33
## [Relationships](resources/relationships.md)
44
## [Resource Definitions](resources/resource-definitions.md)
55

6+
# Reading data
7+
## [Filtering](reading/filtering.md)
8+
## [Sorting](reading/sorting.md)
9+
## [Pagination](reading/pagination.md)
10+
## [Sparse Fieldset Selection](reading/sparse-fieldset-selection.md)
11+
## [Including Relationships](reading/including-relationships.md)
12+
13+
# Writing data
14+
## [Creating](writing/creating.md)
15+
## [Updating](writing/updating.md)
16+
## [Deleting](writing/deleting.md)
17+
618
# [Resource Graph](resource-graph.md)
719
# [Options](options.md)
8-
# [Filtering](filtering.md)
9-
# [Sorting](sorting.md)
10-
# [Pagination](pagination.md)
11-
# [Sparse Fieldset Selection](sparse-fieldset-selection.md)
12-
# [Including Relationships](including-relationships.md)
1320
# [Routing](routing.md)
1421
# [Errors](errors.md)
1522
# [Metadata](meta.md)

‎docs/usage/writing/creating.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Creating resources
2+
3+
A single resource can be created by sending a POST request. The next example creates a new article:
4+
5+
```http
6+
POST /articles HTTP/1.1
7+
8+
{
9+
"data": {
10+
"type": "articles",
11+
"attributes": {
12+
"caption": "A new article!",
13+
"url": "www.website.com"
14+
}
15+
}
16+
}
17+
```
18+
19+
When using client-generated IDs and only attributes from the request have changed, the server returns `204 No Content`.
20+
Otherwise, the server returns `200 OK`, along with the updated resource and its newly assigned ID.
21+
22+
In both cases, a `Location` header is returned that contains the URL to the new resource.
23+
24+
# Creating resources with relationships
25+
26+
It is possible to create a new resource and establish relationships to existing resources in a single request.
27+
The example below creates an article and sets both its owner and tags.
28+
29+
```http
30+
POST /articles HTTP/1.1
31+
32+
{
33+
"data": {
34+
"type": "articles",
35+
"attributes": {
36+
"caption": "A new article!"
37+
},
38+
"relationships": {
39+
"author": {
40+
"data": {
41+
"type": "person",
42+
"id": "101"
43+
}
44+
},
45+
"tags": {
46+
"data": [
47+
{
48+
"type": "tag",
49+
"id": "123"
50+
},
51+
{
52+
"type": "tag",
53+
"id": "456"
54+
}
55+
]
56+
}
57+
}
58+
}
59+
}
60+
```
61+
62+
# Response body
63+
64+
POST requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields`. For example:
65+
66+
```http
67+
POST /articles?include=owner&fields[owner]=firstName HTTP/1.1
68+
69+
{
70+
...
71+
}
72+
```
73+
74+
After the resource has been created on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.

‎docs/usage/writing/deleting.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Deleting resources
2+
3+
A single resource can be deleted using a DELETE request. The next example deletes an article:
4+
5+
```http
6+
DELETE /articles/1 HTTP/1.1
7+
```
8+
9+
This returns `204 No Content` if the resource was successfully deleted. Alternatively, if the resource does not exist, `404 Not Found` is returned.

‎docs/usage/writing/updating.md

+137
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Updating resources
2+
3+
## Updating resource attributes
4+
5+
To modify the attributes of a single resource, send a PATCH request. The next example changes the article caption:
6+
7+
```http
8+
POST /articles HTTP/1.1
9+
10+
{
11+
"data": {
12+
"type": "articles",
13+
"id": "1",
14+
"attributes": {
15+
"caption": "This has changed"
16+
}
17+
}
18+
}
19+
```
20+
21+
This preserves the values of all other unsent attributes and is called a *partial patch*.
22+
23+
When only the attributes that were sent in the request have changed, the server returns `204 No Content`.
24+
But if additional attributes have changed (for example, by a database trigger that refreshes the last-modified date) the server returns `200 OK`, along with all attributes of the updated resource.
25+
26+
## Updating resource relationships
27+
28+
Besides its attributes, the relationships of a resource can be changed using a PATCH request too.
29+
Note that all resources being assigned in a relationship must already exist.
30+
31+
When updating a HasMany relationship, the existing set is replaced by the new set. See below on how to add/remove resources.
32+
33+
The next example replaces both the owner and tags of an article.
34+
35+
```http
36+
PATCH /articles/1 HTTP/1.1
37+
38+
{
39+
"data": {
40+
"type": "articles",
41+
"id": "1",
42+
"relationships": {
43+
"author": {
44+
"data": {
45+
"type": "person",
46+
"id": "101"
47+
}
48+
},
49+
"tags": {
50+
"data": [
51+
{
52+
"type": "tag",
53+
"id": "123"
54+
},
55+
{
56+
"type": "tag",
57+
"id": "456"
58+
}
59+
]
60+
}
61+
}
62+
}
63+
}
64+
```
65+
66+
A HasOne relationship can be cleared by setting `data` to `null`, while a HasMany relationship can be cleared by setting it to an empty array.
67+
68+
By combining the examples above, both attributes and relationships can be updated using a single PATCH request.
69+
70+
## Response body
71+
72+
PATCH requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields`. For example:
73+
74+
```http
75+
PATCH /articles/1?include=owner&fields[owner]=firstName HTTP/1.1
76+
77+
{
78+
...
79+
}
80+
```
81+
82+
After the resource has been updated on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.
83+
Note this only has an effect when `200 OK` is returned.
84+
85+
# Updating relationships
86+
87+
Although relationships can be modified along with resources (as described above), it is also possible to change a single relationship using a relationship URL.
88+
The same rules for clearing the relationship apply. And similar to PATCH on a resource URL, updating a HasMany relationship replaces the existing set.
89+
90+
The next example changes just the owner of an article, by sending a PATCH request to its relationship URL.
91+
92+
```http
93+
PATCH /articles/1/relationships/owner HTTP/1.1
94+
95+
{
96+
"data": {
97+
"type": "person",
98+
"id": "101"
99+
}
100+
}
101+
```
102+
103+
The server returns `204 No Content` when the update is successful.
104+
105+
## Changing HasMany relationships
106+
107+
The POST and DELETE verbs can be used on HasMany relationship URLs to add or remove resources to/from an existing set without replacing it.
108+
109+
The next example adds another tag to the existing set of tags of an article:
110+
111+
```http
112+
POST /articles/1/relationships/tags HTTP/1.1
113+
114+
{
115+
"data": [
116+
{
117+
"type": "tag",
118+
"id": "789"
119+
}
120+
]
121+
}
122+
```
123+
124+
Likewise, the next example removes a single tag from the set of tags of an article:
125+
126+
```http
127+
DELETE /articles/1/relationships/tags HTTP/1.1
128+
129+
{
130+
"data": [
131+
{
132+
"type": "tag",
133+
"id": "789"
134+
}
135+
]
136+
}
137+
```

‎src/JsonApiDotNetCore/Services/JsonApiResourceService.cs

-2
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@
1717

1818
namespace JsonApiDotNetCore.Services
1919
{
20-
// TODO: @ThisPR Add write operations to our documentation.
21-
2220
/// <inheritdoc />
2321
public class JsonApiResourceService<TResource, TId> :
2422
IResourceService<TResource, TId>

0 commit comments

Comments
 (0)