Skip to content

Commit 3bd29b5

Browse files
author
Bart Koelman
committed
Addressed review feedback
1 parent e8e7026 commit 3bd29b5

File tree

6 files changed

+52
-33
lines changed

6 files changed

+52
-33
lines changed

‎docs/usage/resources/relationships.md

+15-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
# Relationships
22

3-
In order for navigation properties to be identified in the model,
4-
they should be labeled with the appropriate attribute (either `HasOne`, `HasMany` or `HasManyThrough`).
3+
A relationship is a named link between two resource types, including a direction.
4+
They are similar to [navigation properties in Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/modeling/relationships).
5+
6+
Relationships come in three flavors: to-one, to-many and many-to-many.
7+
The left side of a relationship is where the relationship is declared, the right side is the resource type it points to.
58

69
## HasOne
710

@@ -15,6 +18,9 @@ public class TodoItem : Identifiable
1518
}
1619
```
1720

21+
The left side of this relationship is of type `TodoItem` (public name: "todoItems") and the right side is of type `Person` (public name: "persons").
22+
23+
1824
## HasMany
1925

2026
This exposes a to-many relationship.
@@ -27,11 +33,14 @@ public class Person : Identifiable
2733
}
2834
```
2935

36+
The left side of this relationship is of type `Person` (public name: "persons") and the right side is of type `TodoItem` (public name: "todoItems").
37+
38+
3039
## HasManyThrough
3140

3241
Earlier versions of Entity Framework Core (up to v5) [did not support](https://github.com/aspnet/EntityFrameworkCore/issues/1368) many-to-many relationships without a join entity.
3342
For this reason, we have decided to fill this gap by allowing applications to declare a relationship as `HasManyThrough`.
34-
JsonApiDotNetCore will expose this relationship to the client the same way as any other `HasMany` attribute.
43+
JsonApiDotNetCore will expose this relationship to the client the same way as any other `HasMany` relationship.
3544
However, under the covers it will use the join type and Entity Framework Core's APIs to get and set the relationship.
3645

3746
```c#
@@ -49,6 +58,9 @@ public class Article : Identifiable
4958
}
5059
```
5160

61+
The left side of this relationship is of type `Article` (public name: "articles") and the right side is of type `Tag` (public name: "tags").
62+
63+
5264
## Name
5365

5466
There are two ways the exposed relationship name is determined:

‎docs/usage/routing.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Routing
22

3+
An endpoint URL provides access to a resource or a relationship. Resource endpoints are divided into:
4+
- Primary endpoints, for example: "/articles" and "/articles/1".
5+
- Secondary endpoints, for example: "/articles/1/author" and "/articles/1/comments".
6+
7+
In the relationship endpoint "/articles/1/relationships/comments", "articles" is the left side of the relationship and "comments" the right side.
8+
39
## Namespacing and Versioning URLs
410
You can add a namespace to all URLs by specifying it in ConfigureServices.
511

‎src/JsonApiDotNetCore/Resources/IResourceDefinition.cs

+8-7
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,8 @@ public interface IResourceDefinition<TResource, TId>
165165
/// </para>
166166
/// </summary>
167167
/// <param name="leftResource">
168-
/// The original resource retrieved from the underlying data store. Its type, <typeparamref name="TResource" />, declares
169-
/// <paramref name="hasOneRelationship" />.
168+
/// The original resource as retrieved from the underlying data store. The indication "left" specifies that <paramref name="hasOneRelationship" /> is
169+
/// declared on <typeparamref name="TResource" />.
170170
/// </param>
171171
/// <param name="hasOneRelationship">
172172
/// The to-one relationship being set.
@@ -194,8 +194,8 @@ Task<IIdentifiable> OnSetToOneRelationshipAsync(TResource leftResource, HasOneAt
194194
/// </para>
195195
/// </summary>
196196
/// <param name="leftResource">
197-
/// The original resource retrieved from the underlying data store. Its type, <typeparamref name="TResource" />, declares
198-
/// <paramref name="hasManyRelationship" />.
197+
/// The original resource as retrieved from the underlying data store. The indication "left" specifies that <paramref name="hasManyRelationship" /> is
198+
/// declared on <typeparamref name="TResource" />.
199199
/// </param>
200200
/// <param name="hasManyRelationship">
201201
/// The to-many relationship being set.
@@ -220,7 +220,8 @@ Task OnSetToManyRelationshipAsync(TResource leftResource, HasManyAttribute hasMa
220220
/// </para>
221221
/// </summary>
222222
/// <param name="leftResourceId">
223-
/// Identifier of the resource that declares <paramref name="hasManyRelationship" />.
223+
/// Identifier of the left resource. The indication "left" specifies that <paramref name="hasManyRelationship" /> is declared on
224+
/// <typeparamref name="TResource" />.
224225
/// </param>
225226
/// <param name="hasManyRelationship">
226227
/// The to-many relationship being added to.
@@ -241,8 +242,8 @@ Task OnAddToRelationshipAsync(TId leftResourceId, HasManyAttribute hasManyRelati
241242
/// </para>
242243
/// </summary>
243244
/// <param name="leftResource">
244-
/// The original resource retrieved from the underlying data store. Its type, <typeparamref name="TResource" />, declares
245-
/// <paramref name="hasManyRelationship" />.
245+
/// The original resource as retrieved from the underlying data store. The indication "left" specifies that <paramref name="hasManyRelationship" /> is
246+
/// declared on <typeparamref name="TResource" />.
246247
/// </param>
247248
/// <param name="hasManyRelationship">
248249
/// The to-many relationship being removed from.

‎test/JsonApiDotNetCoreExampleTests/IntegrationTests/Microservices/TransactionalOutboxPattern/OutboxTests.Group.cs

+9-9
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ namespace JsonApiDotNetCoreExampleTests.IntegrationTests.Microservices.Transacti
1616
public sealed partial class OutboxTests
1717
{
1818
[Fact]
19-
public async Task Create_group_adds_to_outbox()
19+
public async Task Create_group_writes_to_outbox()
2020
{
2121
// Arrange
2222
string newGroupName = _fakers.DomainGroup.Generate().Name;
@@ -63,7 +63,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
6363
}
6464

6565
[Fact]
66-
public async Task Create_group_with_users_adds_to_outbox()
66+
public async Task Create_group_with_users_writes_to_outbox()
6767
{
6868
// Arrange
6969
DomainUser existingUserWithoutGroup = _fakers.DomainUser.Generate();
@@ -145,7 +145,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
145145
}
146146

147147
[Fact]
148-
public async Task Update_group_adds_to_outbox()
148+
public async Task Update_group_writes_to_outbox()
149149
{
150150
// Arrange
151151
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -195,7 +195,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
195195
}
196196

197197
[Fact]
198-
public async Task Update_group_with_users_adds_to_outbox()
198+
public async Task Update_group_with_users_writes_to_outbox()
199199
{
200200
// Arrange
201201
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -282,7 +282,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
282282
}
283283

284284
[Fact]
285-
public async Task Delete_group_adds_to_outbox()
285+
public async Task Delete_group_writes_to_outbox()
286286
{
287287
// Arrange
288288
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -315,7 +315,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
315315
}
316316

317317
[Fact]
318-
public async Task Delete_group_with_users_adds_to_outbox()
318+
public async Task Delete_group_with_users_writes_to_outbox()
319319
{
320320
// Arrange
321321
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -353,7 +353,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
353353
}
354354

355355
[Fact]
356-
public async Task Replace_users_in_group_adds_to_outbox()
356+
public async Task Replace_users_in_group_writes_to_outbox()
357357
{
358358
// Arrange
359359
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -429,7 +429,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
429429
}
430430

431431
[Fact]
432-
public async Task Add_users_to_group_adds_to_outbox()
432+
public async Task Add_users_to_group_writes_to_outbox()
433433
{
434434
// Arrange
435435
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -493,7 +493,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
493493
}
494494

495495
[Fact]
496-
public async Task Remove_users_from_group_adds_to_outbox()
496+
public async Task Remove_users_from_group_writes_to_outbox()
497497
{
498498
// Arrange
499499
DomainGroup existingGroup = _fakers.DomainGroup.Generate();

‎test/JsonApiDotNetCoreExampleTests/IntegrationTests/Microservices/TransactionalOutboxPattern/OutboxTests.User.cs

+11-11
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ namespace JsonApiDotNetCoreExampleTests.IntegrationTests.Microservices.Transacti
1616
public sealed partial class OutboxTests
1717
{
1818
[Fact]
19-
public async Task Create_user_adds_to_outbox()
19+
public async Task Create_user_writes_to_outbox()
2020
{
2121
// Arrange
2222
string newLoginName = _fakers.DomainUser.Generate().LoginName;
@@ -67,7 +67,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
6767
}
6868

6969
[Fact]
70-
public async Task Create_user_in_group_adds_to_outbox()
70+
public async Task Create_user_in_group_writes_to_outbox()
7171
{
7272
// Arrange
7373
DomainGroup existingGroup = _fakers.DomainGroup.Generate();
@@ -135,7 +135,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
135135
}
136136

137137
[Fact]
138-
public async Task Update_user_adds_to_outbox()
138+
public async Task Update_user_writes_to_outbox()
139139
{
140140
// Arrange
141141
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -192,7 +192,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
192192
}
193193

194194
[Fact]
195-
public async Task Update_user_clear_group_adds_to_outbox()
195+
public async Task Update_user_clear_group_writes_to_outbox()
196196
{
197197
// Arrange
198198
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -254,7 +254,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
254254
}
255255

256256
[Fact]
257-
public async Task Update_user_add_to_group_adds_to_outbox()
257+
public async Task Update_user_add_to_group_writes_to_outbox()
258258
{
259259
// Arrange
260260
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -320,7 +320,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
320320
}
321321

322322
[Fact]
323-
public async Task Update_user_move_to_group_adds_to_outbox()
323+
public async Task Update_user_move_to_group_writes_to_outbox()
324324
{
325325
// Arrange
326326
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -389,7 +389,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
389389
}
390390

391391
[Fact]
392-
public async Task Delete_user_adds_to_outbox()
392+
public async Task Delete_user_writes_to_outbox()
393393
{
394394
// Arrange
395395
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -422,7 +422,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
422422
}
423423

424424
[Fact]
425-
public async Task Delete_user_in_group_adds_to_outbox()
425+
public async Task Delete_user_in_group_writes_to_outbox()
426426
{
427427
// Arrange
428428
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -460,7 +460,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
460460
}
461461

462462
[Fact]
463-
public async Task Clear_group_from_user_adds_to_outbox()
463+
public async Task Clear_group_from_user_writes_to_outbox()
464464
{
465465
// Arrange
466466
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -500,7 +500,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
500500
}
501501

502502
[Fact]
503-
public async Task Assign_group_to_user_adds_to_outbox()
503+
public async Task Assign_group_to_user_writes_to_outbox()
504504
{
505505
// Arrange
506506
DomainUser existingUser = _fakers.DomainUser.Generate();
@@ -544,7 +544,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
544544
}
545545

546546
[Fact]
547-
public async Task Replace_group_for_user_adds_to_outbox()
547+
public async Task Replace_group_for_user_writes_to_outbox()
548548
{
549549
// Arrange
550550
DomainUser existingUser = _fakers.DomainUser.Generate();

‎test/JsonApiDotNetCoreExampleTests/IntegrationTests/MultiTenancy/MultiTenancyTests.cs

+3-3
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ public MultiTenancyTests(ExampleIntegrationTestContext<TestableStartup<MultiTena
4141
}
4242

4343
[Fact]
44-
public async Task Get_primary_resources_excludes_other_tenants()
44+
public async Task Get_primary_resources_hides_other_tenants()
4545
{
4646
// Arrange
4747
List<WebShop> shops = _fakers.WebShop.Generate(2);
@@ -68,7 +68,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
6868
}
6969

7070
[Fact]
71-
public async Task Filter_on_primary_resources_excludes_other_tenants()
71+
public async Task Filter_on_primary_resources_hides_other_tenants()
7272
{
7373
// Arrange
7474
List<WebShop> shops = _fakers.WebShop.Generate(2);
@@ -98,7 +98,7 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
9898
}
9999

100100
[Fact]
101-
public async Task Get_primary_resources_with_include_excludes_other_tenants()
101+
public async Task Get_primary_resources_with_include_hides_other_tenants()
102102
{
103103
// Arrange
104104
List<WebShop> shops = _fakers.WebShop.Generate(2);

0 commit comments

Comments
 (0)