Write enhancements (continued)

README.md

@@ -2,7 +2,7 @@
 <img src ="https://raw.githubusercontent.com/json-api-dotnet/JsonApiDotnetCore/master/logo.png" />
 </p>
 
-# JSON API .Net Core
+# JSON:API .NET Core
 
 [![Build status](https://ci.appveyor.com/api/projects/status/5go47hrm0iik0ls3/branch/master?svg=true)](https://ci.appveyor.com/project/jaredcnance/jsonapidotnetcore/branch/master)
 [![Travis](https://travis-ci.org/json-api-dotnet/JsonApiDotNetCore.svg?branch=master)](https://travis-ci.org/json-api-dotnet/JsonApiDotNetCore)
@@ -21,7 +21,7 @@ These are some steps you can take to help you understand what this project is an
 - [Demo [Video]](https://youtu.be/KAMuo6K7VcE)
 - [Our documentation](https://json-api-dotnet.github.io/JsonApiDotNetCore/)
 - [Check out the example projects](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples)
-- [Embercasts: Full Stack Ember with ASP .NET Core](https://www.embercasts.com/course/full-stack-ember-with-dotnet/watch/whats-in-this-course-cs)
+- [Embercasts: Full Stack Ember with ASP.NET Core](https://www.embercasts.com/course/full-stack-ember-with-dotnet/watch/whats-in-this-course-cs)
 
 ## Related Projects
 
@@ -43,7 +43,7 @@ See [our documentation](https://json-api-dotnet.github.io/JsonApiDotNetCore/) fo
 ```csharp
 public class Article : Identifiable
 {
-    [Attr("name")]
+    [Attr]
     public string Name { get; set; }
 }
 ```
@@ -53,12 +53,11 @@ public class Article : Identifiable
 ```csharp
 public class ArticlesController : JsonApiController<Article>
 {
-        public ArticlesController(
-            IJsonApiOptions options,
-            IResourceService<Article> resourceService,
-            ILoggerFactory loggerFactory)
-            : base(options, resourceService, loggerFactory)
-        { }
+    public ArticlesController(IJsonApiOptions options, IResourceService<Article> resourceService,
+        ILoggerFactory loggerFactory)
+        : base(options, resourceService, loggerFactory)
+    {
+    }
 }
 ```
 
@@ -67,14 +66,16 @@ public class ArticlesController : JsonApiController<Article>
 ```csharp
 public class Startup
 {
-    public IServiceProvider ConfigureServices(IServiceCollection services) {
+    public IServiceProvider ConfigureServices(IServiceCollection services)
+    {
         services.AddJsonApi<AppDbContext>();
-        // ...
     }
 
-    public void Configure(IApplicationBuilder app)  {
-        app.UseJsonApi()
-        // ...
+    public void Configure(IApplicationBuilder app)
+    {
+        app.UseRouting();
+        app.UseJsonApi();
+        app.UseEndpoints(endpoints => endpoints.MapControllers());
     }
 }
 ```
@@ -101,26 +102,19 @@ And then to run the tests:
 dotnet test
 ```
 
-#### Cleaning
-
-Sometimes the compiled files can be dirty / corrupt from other branches / failed builds.
-
-```bash
-dotnet clean
-```
-
 #### Compiler warnings
 
 The `Release` build configuration is set to fail on warnings. That means when submitting a PR there shouldn't be any compiler warnings because the CI build it set to `Release`.
 
 ## Compatibility
 
-A lot of changes were introduced in v4.0.0, the following chart should help you with compatibility issues between .NET Core versions
+A lot of changes were introduced in v4, the following chart should help you with compatibility issues between .NET Core versions.
 
-| .NET Core Version | JADNC Version |
-| ----------------- | ------------- |
-| 2.*               | v3.*          |
-| 3.*               | v4.*          |
+| .NET Core Version | EF Core Version | JADNC Version |
+| ----------------- | --------------- | ------------- |
+| 2.x               | 2.x             | v3.x          |
+| 3.x               | 3.x, 5.x        | v4.x          |
+| 5.x               | 5.x             | v4.x          |
 
 ## Trying out the latest build
 

benchmarks/Serialization/JsonApiDeserializerBenchmarks.cs

@@ -3,6 +3,7 @@
 using System.ComponentModel.Design;
 using BenchmarkDotNet.Attributes;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Serialization;
 using JsonApiDotNetCore.Serialization.Objects;
@@ -37,7 +38,8 @@ public JsonApiDeserializerBenchmarks()
             var options = new JsonApiOptions();
             IResourceGraph resourceGraph = DependencyFactory.CreateResourceGraph(options);
             var targetedFields = new TargetedFields();
-            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, new ResourceFactory(new ServiceContainer()), targetedFields, new HttpContextAccessor());
+            var request = new JsonApiRequest();
+            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, new ResourceFactory(new ServiceContainer()), targetedFields, new HttpContextAccessor(), request);
         }
 
         [Benchmark]

benchmarks/Serialization/JsonApiSerializerBenchmarks.cs

@@ -49,7 +49,7 @@ private static FieldsToSerialize CreateFieldsToSerialize(IResourceGraph resource
 
             var accessor = new Mock<IResourceDefinitionAccessor>().Object;
 
-            return new FieldsToSerialize(resourceGraph, constraintProviders, accessor);
+            return new FieldsToSerialize(resourceGraph, constraintProviders, accessor, request);
         }
 
         [Benchmark]

docs/getting-started/install.md

@@ -16,6 +16,6 @@ Install-Package JsonApiDotnetCore
 ```xml
 <ItemGroup>
   <!-- Be sure to check NuGet for the latest version # -->
-  <PackageReference Include="JsonApiDotNetCore" Version="3.0.0" />
+  <PackageReference Include="JsonApiDotNetCore" Version="4.0.0" />
 </ItemGroup>
 ```

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/extensibility/repositories.md

@@ -3,7 +3,7 @@
 If you want to use a data access technology other than Entity Framework Core, you can create an implementation of `IResourceRepository<TResource, TId>`.
 If you only need minor changes you can override the methods defined in `EntityFrameworkCoreRepository<TResource, TId>`.
 
-The repository should then be added to the service collection in Startup.cs.
+The repository should then be registered in Startup.cs.
 
 ```c#
 public void ConfigureServices(IServiceCollection services)
@@ -12,6 +12,21 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
+In v4.0 we introduced an extension method that you can use to register a resource repository on all of its JsonApiDotNetCore interfaces.
+This is helpful when you implement a subset of the resource interfaces and want to register them all in one go.
+
+Note: If you're using service discovery, this happens automatically.
+
+```c#
+public class Startup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddResourceRepository<ArticleRepository>();
+    }
+}
+```
+
 A sample implementation that performs authorization might look like this.
 
 All of the methods in EntityFrameworkCoreRepository will use the `GetAll()` method to get the `DbSet<TResource>`, so this is a good method to apply filters such as user or tenant authorization.

docs/usage/extensibility/services.md

@@ -115,7 +115,7 @@ IResourceService
         PATCH /{id}/relationships/{relationship}
 ```
 
-In order to take advantage of these interfaces you first need to inject the service for each implemented interface.
+In order to take advantage of these interfaces you first need to register the service for each implemented interface.
 
 ```c#
 public class ArticleService : ICreateService<Article>, IDeleteService<Article>
@@ -136,6 +136,8 @@ public class Startup
 In v3.0 we introduced an extension method that you can use to register a resource service on all of its JsonApiDotNetCore interfaces.
 This is helpful when you implement a subset of the resource interfaces and want to register them all in one go.
 
+Note: If you're using service discovery, this happens automatically.
+
 ```c#
 public class Startup
 {

docs/usage/including-relationships.md → docs/usage/reading/including-relationships.md

@@ -47,7 +47,7 @@ GET /articles/1?include=comments HTTP/1.1
 
 ## Nested Inclusions
 
-_since v3.0.0_
+_since v3_
 
 JsonApiDotNetCore also supports nested inclusions.
 This allows you to include data across relationships by using a period-delimited relationship path, for example:

docs/usage/resource-graph.md

@@ -1,6 +1,6 @@
 # The Resource Graph
 
-_NOTE: prior to 3.0.0 this was called the `ContextGraph`_
+_NOTE: prior to v4 this was called the `ContextGraph`_
 
 The `ResourceGraph` is a map of all the json:api resources and their relationships that your API serves.
 

docs/usage/resources/relationships.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/resources/resource-definitions.md

@@ -193,7 +193,7 @@ public class EmployeeDefinition : JsonApiResourceDefinition<Employee>
 
 ## Custom query string parameters
 
-_since v3.0.0_
+_since v3_
 
 You can define additional query string parameters with the LINQ expression that should be used.
 If the key is present in a query string, the supplied LINQ expression will be added to the database query.

docs/usage/toc.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/writing/creating.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.

docs/usage/writing/deleting.md

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