Skip to content

Commit a8e3525

Browse files
committed
docs: update hooks guide
1 parent b4777b4 commit a8e3525

File tree

1 file changed

+83
-85
lines changed

1 file changed

+83
-85
lines changed

docs/usage/resources/hooks.md

Lines changed: 83 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11

22
# Resource Hooks
3-
This section covers the usage of **Resource Hooks**, which is a feature of`ResourceDefinition<T>`. See the [ResourceDefinition usage guide](resource-definitions.md) for a general explanation on how to set up a `ResourceDefinition<T>`.
3+
This section covers the usage of **Resource Hooks**, which is a feature of`ResourceDefinition<T>`. See the [ResourceDefinition usage guide](resource-definitions.md) for a general explanation on how to set up a `ResourceDefinition<T>`. For a quick start, jump right to the [Getting started: most minimal example](#getting-started-most-minimal-example) section.
44

55
By implementing resource hooks on a `ResourceDefintion<T>`, it is possible to intercept the execution of the **Resource Service Layer** (RSL) in various ways. This enables the developer to conveniently define business logic without having to override the RSL. It can be used to implement e.g.
66
* Authorization
@@ -11,19 +11,18 @@ By implementing resource hooks on a `ResourceDefintion<T>`, it is possible to in
1111
This usage guide covers the following sections
1212
1. [**Semantics: pipelines, actions and hooks**](#semantics-pipelines-actions-and-hooks).
1313
Understanding the semantics will be helpful in identifying which hooks on `ResourceDefinition<T>` you need to implement for your use-case.
14-
2. [**Hook execution overview**](#hook-execution-overview)
15-
A table overview of all pipelines and involved hooks
16-
3. [**Examples: basic usage**](#examples-basic-usage)
14+
2. [**Basic usage**](#basic-usage)
1715
* [**Getting started: most minimal example**](#getting-started-most-minimal-example)
1816
* [**Logging**](#logging)
1917
* [**Transforming data with OnReturn**](#transforming-data-with-onreturn)
2018
* [**Loading database values**](#loading-database-values)
21-
5. [**Examples: advanced usage**](#examples-advanced-usage)
19+
3. [**Advanced usage**](#advanced-usage)
2220
* [**Simple authorization: explicitly affected resources**](#simple-authorization-explicitly-affected-resources)
2321
* [**Advanced authorization: implicitly affected resources**](#advanced-authorization-implicitly-affected-resources)
2422
* [**Synchronizing data across microservices**](#synchronizing-data-across-microservices)
2523
* [**Hooks for many-to-many join tables**](#hooks-for-many-to-many-join-tables)
26-
24+
4. [**Hook execution overview**](#hook-execution-overview)
25+
A table overview of all pipelines and involved hooks
2726

2827
# 1. Semantics: pipelines, actions and hooks
2928

@@ -91,84 +90,7 @@ Any return content can be intercepted and transformed as desired by implementing
9190
<br><br>
9291
For an overview of all pipelines, hooks and actions, see the table below, and for more detailed information about the available hooks, see the [IResourceHookContainer<T>](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/ab1f96d8255532461da47d290c5440b9e7e6a4a5/src/JsonApiDotNetCore/Hooks/IResourceHookContainer.cs) interface.
9392

94-
# 2. Hook execution overview
95-
96-
97-
This table below shows the involved hooks per pipeline.
98-
<table>
99-
<tr>
100-
<th rowspan="2">Pipeline</th>
101-
<th colspan="5"><span style="font-style:italic">Execution Flow</span></th>
102-
</tr>
103-
<tr>
104-
<td align="center"><b>Before Hooks</b></td>
105-
<td align="center" colspan="2"><b>Repository Actions</td>
106-
<td align="center"><b>After Hooks</td>
107-
<td align="center"><b>OnReturn</td>
108-
</tr>
109-
<tr>
110-
<td>Get</td>
111-
<td align="center">BeforeRead</td>
112-
<td align="center" colspan="2" rowspan="3">read</td>
113-
<td align="center">AfterRead</td>
114-
<td align="center">✅</td>
115-
</tr>
116-
<tr>
117-
<td>GetSingle</td>
118-
<td align="center">BeforeRead</td>
119-
<td align="center">AfterRead</td>
120-
<td align="center">✅</td>
121-
</tr>
122-
<tr>
123-
<td>GetRelationship</td>
124-
<td align="center">BeforeRead</td>
125-
<td align="center">AfterRead</td>
126-
<td align="center">✅</td>
127-
</tr>
128-
<tr>
129-
<td>Post</td>
130-
<td align="center">BeforeCreate</td>
131-
<td align="center" colspan="2">create<br>update relationship</td>
132-
<td align="center">AfterCreate</td>
133-
<td align="center">✅</td>
134-
</tr>
135-
<tr>
136-
<td>Patch</td>
137-
<td align="center">BeforeUpdate<br>BeforeUpdateRelationship<br>BeforeImplicitUpdateRelationship</td>
138-
<td align="center" colspan="2">update<br>update relationship<br>implicit update relationship</td>
139-
<td align="center">AfterUpdate<br>AfterUpdateRelationship</td>
140-
<td align="center">✅</td>
141-
</tr>
142-
<tr>
143-
<td>PatchRelationship</td>
144-
<td align="center">BeforeUpdate<br>BeforeUpdateRelationship</td>
145-
<td align="center" colspan="2">update<br>update relationship<br>implicit update relationship</td>
146-
<td align="center">AfterUpdate<br>AfterUpdateRelationship</td>
147-
<td align="center">❌</td>
148-
</tr>
149-
<tr>
150-
<td>Delete</td>
151-
<td align="center">BeforeDelete</td>
152-
<td align="center" colspan="2">delete<br>implicit update relationship</td>
153-
<td align="center">AfterDelete</td>
154-
<td align="center">❌</td>
155-
</tr>
156-
<tr>
157-
<td>BulkPost</td>
158-
<td colspan="5" align="center"><i>Not yet supported</i></td>
159-
</tr>
160-
<tr>
161-
<td>BulkPatch</td>
162-
<td colspan="5" align="center"><i>Not yet supported</i></td>
163-
</tr>
164-
<tr>
165-
<td>BulkDelete</td>
166-
<td colspan="5" align="center"><i>Not yet supported</i></td>
167-
</tr>
168-
</table>
169-
170-
171-
# 3. Examples: basic usage
93+
# 2. Basic usage
17294

17395
## Getting started: most minimal example
17496
To use resource hooks, you are required to turn them on in your `startup.cs` configuration
@@ -402,7 +324,7 @@ Note that there are some hooks that the `LoadDatabaseValues` option and attribu
402324

403325

404326

405-
# 3. Examples: advanced usage
327+
# 3. Advanced usage
406328

407329
## Simple authorization: explicitly affected resources
408330
Resource hooks can be used to easily implement authorization in your application. As an example, consider the case in which an API user is not allowed to see anonymous people, which is reflected by the `Anonymous` property on `Person` being set to true`true`. The API should handle this as follows:
@@ -619,3 +541,79 @@ Then, for the same request `GET /articles?include=tags`, the order of execution
619541
And the included collection of tags per article will only contain tags that were added less than two weeks ago.
620542

621543
Note that the introduced inheritance and added relationship attributes does not further affect the many-to-many relationship internally.
544+
545+
# 4. Hook execution overview
546+
547+
548+
This table below shows the involved hooks per pipeline.
549+
<table>
550+
<tr>
551+
<th rowspan="2">Pipeline</th>
552+
<th colspan="5"><span style="font-style:italic">Execution Flow</span></th>
553+
</tr>
554+
<tr>
555+
<td align="center"><b>Before Hooks</b></td>
556+
<td align="center" colspan="2"><b>Repository Actions</td>
557+
<td align="center"><b>After Hooks</td>
558+
<td align="center"><b>OnReturn</td>
559+
</tr>
560+
<tr>
561+
<td>Get</td>
562+
<td align="center">BeforeRead</td>
563+
<td align="center" colspan="2" rowspan="3">read</td>
564+
<td align="center">AfterRead</td>
565+
<td align="center"></td>
566+
</tr>
567+
<tr>
568+
<td>GetSingle</td>
569+
<td align="center">BeforeRead</td>
570+
<td align="center">AfterRead</td>
571+
<td align="center"></td>
572+
</tr>
573+
<tr>
574+
<td>GetRelationship</td>
575+
<td align="center">BeforeRead</td>
576+
<td align="center">AfterRead</td>
577+
<td align="center"></td>
578+
</tr>
579+
<tr>
580+
<td>Post</td>
581+
<td align="center">BeforeCreate</td>
582+
<td align="center" colspan="2">create<br>update relationship</td>
583+
<td align="center">AfterCreate</td>
584+
<td align="center"></td>
585+
</tr>
586+
<tr>
587+
<td>Patch</td>
588+
<td align="center">BeforeUpdate<br>BeforeUpdateRelationship<br>BeforeImplicitUpdateRelationship</td>
589+
<td align="center" colspan="2">update<br>update relationship<br>implicit update relationship</td>
590+
<td align="center">AfterUpdate<br>AfterUpdateRelationship</td>
591+
<td align="center"></td>
592+
</tr>
593+
<tr>
594+
<td>PatchRelationship</td>
595+
<td align="center">BeforeUpdate<br>BeforeUpdateRelationship</td>
596+
<td align="center" colspan="2">update<br>update relationship<br>implicit update relationship</td>
597+
<td align="center">AfterUpdate<br>AfterUpdateRelationship</td>
598+
<td align="center"></td>
599+
</tr>
600+
<tr>
601+
<td>Delete</td>
602+
<td align="center">BeforeDelete</td>
603+
<td align="center" colspan="2">delete<br>implicit update relationship</td>
604+
<td align="center">AfterDelete</td>
605+
<td align="center"></td>
606+
</tr>
607+
<tr>
608+
<td>BulkPost</td>
609+
<td colspan="5" align="center"><i>Not yet supported</i></td>
610+
</tr>
611+
<tr>
612+
<td>BulkPatch</td>
613+
<td colspan="5" align="center"><i>Not yet supported</i></td>
614+
</tr>
615+
<tr>
616+
<td>BulkDelete</td>
617+
<td colspan="5" align="center"><i>Not yet supported</i></td>
618+
</tr>
619+
</table>

0 commit comments

Comments
 (0)