Skip to content

Commit

Permalink
docs: #500 document ref responses
Browse files Browse the repository at this point in the history
  • Loading branch information
ascott18 committed Feb 5, 2025
1 parent 1ca635d commit 97f7ded
Show file tree
Hide file tree
Showing 2 changed files with 6 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
"readonly",
"snapshotted",
"Stampable",
"TPCT",
"treeshaken",
"typeof",
"unplugin",
Expand Down
5 changes: 5 additions & 0 deletions docs/modeling/model-components/data-sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,11 @@ list.$load(1);
All methods on `IDataSource<T>` take a parameter that contains all the client-specified parameters for things paging, searching, sorting, and filtering information. Almost all virtual methods on `StandardDataSource` are also passed the relevant set of parameters. The parameters are contained in the `IDataSourceParameters` type or one of its derivatives, `IFilterParameters` (adds filtering and search parameters) or `IListParameters` (filters + pagination). These parameters can be set on the client through the `$params` member on [ViewModels](/stacks/vue/layers/viewmodels.md#viewmodels) and [ListViewModels](/stacks/vue/layers/viewmodels.md#listviewmodels), or less commonly by passing them directly when using the [API Clients](/stacks/vue/layers/api-clients.md) directly.


### Ref Responses

An additional parameter on `DataSourceParameters` is available on the client only - `refResponse`. If set to true - e.g. `listVm.$params.refResponse = true;`, Coalesce will pass a header value of `Accept: application/json+ref` with the API request. This will instruct the server to use [System.Text.Json's PreserveReferences handling](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/preserve-references#preserve-references-and-handle-circular-references) when serializing the response. This allows identical objects that occur multiple times in the response to only have one copy sent across the wire. This also results in only a single, shared instance of this object on the client in the results from the API clients, cascading through to the ViewModels as well. This can significantly reduce response sizes by deduplicating multiple copies of the same data, as well as CPU and memory load on both the client and server.


## Custom Parameters

On any data source that you create, you may add additional properties annotated with `[Coalesce]` that will then be exposed as parameters to the client. These property parameters can be any type supported by Coalesce, including primitives, dates, [Entity Models](/modeling/model-types/entities.md), [External Types](/modeling/model-types/external-types.md), or collections of these types.
Expand Down

0 comments on commit 97f7ded

Please sign in to comment.