Skip to content

Commit f61ca57

Browse files
bkoelmanbkoelman
committed
Add FAQ and Common Pitfalls to docs
1 parent 18cb4eb commit f61ca57

File tree

5 files changed

+303
-5
lines changed

5 files changed

+303
-5
lines changed

‎docs/getting-started/faq.md

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Frequently Asked Questions
2+
3+
#### Where can I find documentation and examples?
4+
While the [documentation](~/usage/resources/index.md) covers basic features and a few runnable example projects are available [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples),
5+
many more advanced use cases are available as integration tests [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests), so be sure to check them out!
6+
7+
#### Why can't I use OpenAPI?
8+
Due to the mismatch between the JSON:API structure and the shape of ASP.NET controller methods, this does not work out of the box.
9+
This is high on our agenda and we're steadily making progress, but it's quite complex and far from complete.
10+
See [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1046) for the current status, which contains instructions on trying out the latest build.
11+
12+
#### What's available to implement a JSON:API client?
13+
It depends on the programming language used. There's an overwhelming list of client libraries at https://jsonapi.org/implementations/#client-libraries.
14+
15+
The JSON object model inside JsonApiDotNetCore is tweaked for server-side handling (be tolerant at input and strict at output).
16+
While you technically *could* use our `JsonSerializer` converters from a .NET client application with some hacks, we don't recommend it.
17+
You'll need to build the resource graph on the client and rely on internal implementation details that are subject to change in future versions.
18+
19+
In the long term, we'd like to solve this through OpenAPI, which enables to generate a (statically typed) client library in various languages.
20+
21+
#### How can I debug my API project?
22+
Due to auto-generated controllers, you may find it hard to determine where to put your breakpoints.
23+
In Visual Studio, controllers are accessible below **Solution Explorer > Project > Dependencies > Analyzers > JsonApiDotNetCore.SourceGenerators**.
24+
25+
After turning on [Source Link](https://devblogs.microsoft.com/dotnet/improving-debug-time-productivity-with-source-link/#enabling-source-link) (which enables to download the JsonApiDotNetCore source code from GitHub), you can step into our source code and add breakpoints there too.
26+
27+
Here are some key places in the execution pipeline to set a breakpoint:
28+
- `JsonApiRoutingConvention.Apply`: Controllers are registered here (executes once at startup)
29+
- `JsonApiMiddleware.InvokeAsync`: Content negotiation and `IJsonApiRequest` setup
30+
- `QueryStringReader.ReadAll`: Parses the query string parameters
31+
- `JsonApiReader.ReadAsync`: Parses the request body
32+
- `OperationsProcessor.ProcessAsync`: Entry point for handling atomic operations
33+
- `JsonApiResourceService`: Called by controllers, delegating to the repository layer
34+
- `EntityFrameworkCoreRepository.ApplyQueryLayer`: Builds the `IQueryable<>` that is offered to Entity Framework Core (which turns it into SQL)
35+
- `JsonApiWriter.WriteAsync`: Renders the response body
36+
- `ExceptionHandler.HandleException`: Interception point for thrown exceptions
37+
38+
Aside from debugging, you can get more info by:
39+
- Including exception stack traces and incoming request bodies in error responses, as well as writing human-readable JSON:
40+
41+
```c#
42+
// Program.cs
43+
builder.Services.AddJsonApi<AppDbContext>(options =>
44+
{
45+
options.IncludeExceptionStackTraceInErrors = true;
46+
options.IncludeRequestBodyInErrors = true;
47+
options.SerializerOptions.WriteIndented = true;
48+
});
49+
```
50+
- Turning on verbose logging and logging of executed SQL statements, by adding the following to your `appsettings.Development.json`:
51+
52+
```json
53+
{
54+
"Logging": {
55+
"LogLevel": {
56+
"Default": "Warning",
57+
"Microsoft.EntityFrameworkCore.Database.Command": "Information",
58+
"JsonApiDotNetCore": "Verbose"
59+
}
60+
}
61+
}
62+
```
63+
64+
#### What if my JSON:API resources do not exactly match the shape of my database tables?
65+
We often find users trying to write custom code to solve that. They usually get it wrong or incomplete, and it may not perform well.
66+
Or it simply fails because it cannot be translated to SQL.
67+
The good news is that there's an easier solution most of the time: configure Entity Framework Core mappings to do the work.
68+
It certainly pays off to read up on its capabilities at [Creating and Configuring a Model](https://learn.microsoft.com/en-us/ef/core/modeling/).
69+
Another great resource is [Learn Entity Framework Core](https://www.learnentityframeworkcore.com/configuration).
70+
71+
#### Can I share my resource models with .NET Framework projects?
72+
Yes, you can. Put your model classes in a separate project that only references [JsonApiDotNetCore.Annotations](https://www.nuget.org/packages/JsonApiDotNetCore.Annotations/).
73+
This package contains just the JSON:API attributes and targets NetStandard 1.0, which makes it flexible to consume.
74+
At startup, use [Auto-discovery](~/usage/resource-graph.md#auto-discovery) and point it to your shared project.
75+
76+
#### What's the best place to put my custom business/validation logic?
77+
For basic input validation, use the attributes from [ASP.NET ModelState Validation](https://learn.microsoft.com/en-us/aspnet/core/mvc/models/validation?source=recommendations&view=aspnetcore-7.0#built-in-attributes) to get the best experience.
78+
JsonApiDotNetCore is aware of them and adjusts behavior accordingly. And it produces the best possible error responses.
79+
80+
For non-trivial business rules that require custom code, the place to be is [Resource Definitions](~/usage/extensibility/resource-definitions.md).
81+
They provide a callback-based model where you can respond to everything going on.
82+
The great thing is that your callbacks are invoked for various endpoints.
83+
For example, the filter callback on Author executes at `GET /authors?filter=`, `GET /books/1/authors?filter=` and `GET /books?include=authors?filter[authors]=`.
84+
Likewise, the callbacks for changing relationships execute for POST/PATCH resource endpoints, as well as POST/PATCH/DELETE relationship endpoints.
85+
86+
#### Can API users send multiple changes in a single request?
87+
Yes, just activate [atomic operations](~/usage/writing/bulk-batch-operations.md).
88+
It enables to send multiple changes in a batch request, which are executed in a database transaction.
89+
If something fails, all changes are rolled back. The error response indicates which operation failed.
90+
91+
#### Is there any way to add `[Authorize(Roles = "...")]` to the generated controllers?
92+
Sure, this is possible. Simply add the attribute at the class level.
93+
See the docs on [Augmenting controllers](~/usage/extensibility/controllers.md#augmenting-controllers).
94+
95+
#### How do I expose non-JSON:API endpoints?
96+
You can add your own controllers that do not derive from `(Base)JsonApiController` or `(Base)JsonApiOperationsController`.
97+
Whatever you do in those is completely ignored by JsonApiDotNetCore.
98+
This is useful if you want to add a few RPC-style endpoints or provide binary file uploads/downloads.
99+
100+
A middle-ground approach is to add custom action methods to existing JSON:API controllers.
101+
While you can route them they way you like, they must return JSON:API resources.
102+
And on error, a JSON:API error response is produced.
103+
This is useful if you want to stay in the JSON:API-compliant world, but need to expose something on-standard, for example: `GET /users/me`.
104+
105+
#### How do I optimize for high scalability and prevent denial of service?
106+
Furtunately, JsonApiDotNetCore [scales pretty well](https://github.com/json-api-dotnet/PerformanceReports) under high load and/or large database tables.
107+
It never executes filtering, sorting or pagination in-memory and tries pretty hard to produce the most efficient query possible.
108+
There are a few things to keep in mind, though:
109+
- Prevent users from executing slow queries by locking down [attribute capabilities](~/usage/resources/attributes.md#capabilities) and [relationship capabilities](~/usage/resources/relationships.md#capabilities).
110+
Ensure the right database indexes are in place for what you enable.
111+
- Prevent users from fetching lots of data by tweaking [maximum page size/number](~/usage/options.md#pagination) and [maximum include depth](~/usage/options.md#maximum-include-depth).
112+
- Tell your users to utilize [E-Tags](~/usage/caching.md) to reduce network traffic.
113+
- Not included in JsonApiDotNetCore: Apply general practices such as rate limiting, load balancing, authentication/authorization, block very large URLs/request bodies etc.
114+
115+
#### Can I offload requests to a background process?
116+
Yes, that's possible. Override controller methods to return `HTTP 202 Accepted`, with a `Location` HTTP header where users can retrieve the result.
117+
Your controller method needs to store the request state (URL, query string and request body) in a qeueue, which your background process can read from.
118+
From within your background process job handler, reconstruct the request state, execute the appropriate `JsonApiResourceService` method and store the result.
119+
There's a basic example available at https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1144, which processes a captured query string.
120+
121+
#### What if I don't want to use Entity Framework Core?
122+
This basically means you'll need to implement data access yourself. There are two approaches for interception: at the resource service level and at the repository level.
123+
Either way, you can use the built-in query string and request body parsing, as well as routing, error handling and rendering of responses.
124+
125+
Here are some injectable request-scoped types to be aware of:
126+
- `IJsonApiRequest`: This contains routing information, such as whether a primary, secondary or relationship endpoint is being accessed.
127+
- `ITargetedFields`: Lists the attributes and relationships from an incoming POST/PATCH resource request. Any fields missing there should not be stored (partial updates).
128+
- `IEnumerable<IQueryConstraintProvider>`: Provides access to the parsed query string parameters.
129+
- `IEvaluatedIncludeCache`: This tells the response serializer which related resources to render, which you need to populate.
130+
- `ISparseFieldSetCache`: This tells the response serializer which fields to render in the attributes and relationship objects. You need to populate this as well.
131+
132+
You may also want to inject the singletons `IJsonApiOptions` (contains settings like default page size) and `IResourceGraph` (the JSON:API model of resources and relationships).
133+
134+
So, back to the topic of where to intercept. It helps to familiarize yourself with the [execution pipeline](~/internals/queries.md).
135+
Replacing at the service level is the simplest. But it means you'll need to read the parsed query string parameters and invoke
136+
all resource definition callbacks yourself. And you won't get change detection (HTTP 203 Not Modified).
137+
Take a look at [JsonApiResourceService](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Services/JsonApiResourceService.cs) to see what you're missing out on.
138+
139+
You'll get a lot more out of the box if replacing at the repository level instead. There's no need to apply options, analyze query strings or populate caches for the serializer.
140+
And most resource definition callbacks are handled.
141+
That's because the built-in resource service translates all JSON:API aspects of the request into a database-agnostic data structure called `QueryLayer`.
142+
Now the hard part for you becomes reading that data structure and producing data access calls from that.
143+
If your data store provides a LINQ provider, you may reuse most of [QueryableBuilder](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Queries/Internal/QueryableBuilding/QueryableBuilder.cs),
144+
which drives the translation into [System.Linq.Expressions](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/expression-trees/).
145+
Note however that it also produces calls to `.Include("")`, which is an Entity Framework Core-specific extension method, so you'll likely need to prevent that from happening.
146+
We use this for accessing [MongoDB](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb/blob/674889e037334e3f376550178ce12d0842d7560c/src/JsonApiDotNetCore.MongoDb/Queries/Internal/QueryableBuilding/MongoQueryableBuilder.cs).
147+
148+
> [!TIP]
149+
> [ExpressionTreeVisualizer](https://github.com/zspitz/ExpressionTreeVisualizer) is very helpful in trying to debug LINQ expression trees!
150+
151+
#### Anything else I should be aware of?
152+
See [Common Pitfalls](~/usage/common-pitfalls.md).

‎docs/getting-started/toc.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# [Installation](install.md)
2+
3+
# [Step By Step](step-by-step.md)
4+
5+
# [FAQ](faq.md)

‎docs/getting-started/toc.yml

-5
This file was deleted.

0 commit comments

Comments
 (0)