Added documentation

Author: Bart Koelman

docs/internals/index.md

@@ -1,3 +1,3 @@
 # Internals
 
-The section contains overviews for the inner workings of the JsonApiDotNetCore library.
+This section contains overviews for the inner workings of the JsonApiDotNetCore library.

docs/request-examples/index.md

@@ -45,22 +45,22 @@ _Note that cURL requires "[" and "]" in URLs to be escaped._
 
 # Writing data
 
-### Create
+### Create resource
 
 [!code-ps[REQUEST](010_CREATE_Person.ps1)]
 [!code-json[RESPONSE](010_CREATE_Person_Response.json)]
 
-### Create with relationship
+### Create resource with relationship
 
 [!code-ps[REQUEST](011_CREATE_Book-with-Author.ps1)]
 [!code-json[RESPONSE](011_CREATE_Book-with-Author_Response.json)]
 
-### Update
+### Update resource
 
 [!code-ps[REQUEST](012_PATCH_Book.ps1)]
 [!code-json[RESPONSE](012_PATCH_Book_Response.json)]
 
-### Delete
+### Delete resource
 
 [!code-ps[REQUEST](013_DELETE_Book.ps1)]
 [!code-json[RESPONSE](013_DELETE_Book_Response.json)]

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

@@ -20,9 +20,6 @@ public class TodoItem : Identifiable<int>
 }
 ```
 
-The convention used to locate the foreign key property (e.g. `OwnerId`) can be changed on
-the @JsonApiDotNetCore.Configuration.JsonApiOptions#JsonApiDotNetCore_Configuration_JsonApiOptions_RelatedIdMapper
-
 ## HasMany
 
 ```c#

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

@@ -3,13 +3,20 @@
 ## [Relationships](resources/relationships.md)
 ## [Resource Definitions](resources/resource-definitions.md)
 
+# Reading data
+## [Filtering](reading/filtering.md)
+## [Sorting](reading/sorting.md)
+## [Pagination](reading/pagination.md)
+## [Sparse Fieldset Selection](reading/sparse-fieldset-selection.md)
+## [Including Relationships](reading/including-relationships.md)
+
+# Writing data
+## [Creating](writing/creating.md)
+## [Updating](writing/updating.md)
+## [Deleting](writing/deleting.md)
+
 # [Resource Graph](resource-graph.md)
 # [Options](options.md)
-# [Filtering](filtering.md)
-# [Sorting](sorting.md)
-# [Pagination](pagination.md)
-# [Sparse Fieldset Selection](sparse-fieldset-selection.md)
-# [Including Relationships](including-relationships.md)
 # [Routing](routing.md)
 # [Errors](errors.md)
 # [Metadata](meta.md)

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

@@ -0,0 +1,74 @@
+# Creating resources
+
+A single resource can be created by sending a POST request. The next example creates a new article:
+
+```http
+POST /articles HTTP/1.1
+
+{
+  "data": {
+    "type": "articles",
+    "attributes": {
+      "caption": "A new article!",
+      "url": "www.website.com"
+    }
+  }
+}
+```
+
+When using client-generated IDs and only attributes from the request have changed, the server returns `204 No Content`.
+Otherwise, the server returns `200 OK`, along with the updated resource and its newly assigned ID.
+
+In both cases, a `Location` header is returned that contains the URL to the new resource.
+
+# Creating resources with relationships
+
+It is possible to create a new resource and establish relationships to existing resources in a single request.
+The example below creates an article and sets both its owner and tags.
+
+```http
+POST /articles HTTP/1.1
+
+{
+  "data": {
+    "type": "articles",
+    "attributes": {
+      "caption": "A new article!"
+    },
+    "relationships": {
+      "author": {
+        "data": {
+          "type": "person",
+          "id": "101"
+        }
+      },
+      "tags": {
+        "data": [
+          {
+            "type": "tag",
+            "id": "123"
+          },
+          {
+            "type": "tag",
+            "id": "456"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+# Response body
+
+POST requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields`. For example:
+
+```http
+POST /articles?include=owner&fields[owner]=firstName HTTP/1.1
+
+{
+  ...
+}
+```
+
+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.