Skip to content

Commit 7f59641

Browse files
maureimaurei
committed
docs: query parameters wiki
1 parent b88d8e7 commit 7f59641

32 files changed

+227
-93
lines changed

‎benchmarks/Query/QueryParser_Benchmarks.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ private void Run(int iterations, Action action) {
5757
}
5858

5959
// this facade allows us to expose and micro-benchmark protected methods
60-
private class BenchmarkFacade : QueryParser {
60+
private class BenchmarkFacade : QueryParameterParser {
6161
public BenchmarkFacade(
6262
IRequestContext currentRequest,
6363
JsonApiOptions options) : base(currentRequest, options) { }

‎src/JsonApiDotNetCore/Extensions/IServiceCollectionExtensions.cs

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ public static void AddJsonApiInternals(
195195
services.AddScoped<IJsonApiReader, JsonApiReader>();
196196
services.AddScoped<IGenericProcessorFactory, GenericProcessorFactory>();
197197
services.AddScoped(typeof(GenericProcessor<>));
198-
services.AddScoped<IQueryParser, QueryParser>();
198+
services.AddScoped<IQueryParameterParser, QueryParameterParser>();
199199
services.AddScoped<ITargetedFields, TargetedFields>();
200200
services.AddScoped<IFieldsExplorer, FieldsExplorer>();
201201
services.AddScoped<IResourceDefinitionProvider, ResourceDefinitionProvider>();
@@ -220,13 +220,13 @@ private static void AddQueryParameterServices(IServiceCollection services)
220220
services.AddScoped<IOmitDefaultService, OmitDefaultService>();
221221
services.AddScoped<IOmitNullService, OmitNullService>();
222222

223-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<IIncludeService>());
224-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<IFilterService>());
225-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<ISortService>());
226-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<ISparseFieldsService>());
227-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<IPageService>());
228-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<IOmitDefaultService>());
229-
services.AddScoped<IParsableQueryParameter>(sp => sp.GetService<IOmitNullService>());
223+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<IIncludeService>());
224+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<IFilterService>());
225+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<ISortService>());
226+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<ISparseFieldsService>());
227+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<IPageService>());
228+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<IOmitDefaultService>());
229+
services.AddScoped<IQueryParameterService>(sp => sp.GetService<IOmitNullService>());
230230
}
231231

232232

‎src/JsonApiDotNetCore/Internal/Query/BaseQuery.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ namespace JsonApiDotNetCore.Internal.Query
66
/// </summary>
77
public abstract class BaseQuery
88
{
9-
public BaseQuery(string target)
9+
protected BaseQuery(string target)
1010
{
1111
Target = target;
1212
var properties = target.Split(QueryConstants.DOT);

‎src/JsonApiDotNetCore/Internal/Query/BaseQueryContext.cs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
namespace JsonApiDotNetCore.Internal.Query
44
{
55
/// <summary>
6-
/// A context class that provides extra meta data for a <see cref="TQuery"/>.
7-
/// Used internally.
6+
/// A context class that provides extra meta data for a <see cref="TQuery"/>
7+
/// that is used when applying url queries internally.
88
/// </summary>
99
public abstract class BaseQueryContext<TQuery> where TQuery : BaseQuery
1010
{
11-
public BaseQueryContext(TQuery query)
11+
protected BaseQueryContext(TQuery query)
1212
{
1313
Query = query;
1414
}
@@ -24,8 +24,8 @@ public string GetPropertyPath()
2424
{
2525
if (IsAttributeOfRelationship)
2626
return string.Format("{0}.{1}", Relationship.InternalRelationshipName, Attribute.InternalAttributeName);
27-
else
28-
return Attribute.InternalAttributeName;
27+
28+
return Attribute.InternalAttributeName;
2929
}
3030
}
3131
}

‎src/JsonApiDotNetCore/Internal/Query/FilterQuery.cs

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,10 @@
55
namespace JsonApiDotNetCore.Internal.Query
66
{
77
/// <summary>
8-
/// Represents the filter[field]=op:value query from the URL.
8+
/// Internal representation of the raw articles?filter[X]=Y query from the URL.
99
/// </summary>
1010
public class FilterQuery : BaseQuery
1111
{
12-
/// <summary>
13-
/// Allows you to filter the query, via the methods shown at
14-
/// <see href="https://json-api-dotnet.github.io/#/filtering">HERE</see>
15-
/// </summary>
16-
/// <param name="value">the value this attribute should be</param>
17-
/// <param name="operation">possible values: eq, ne, lt, gt, le, ge, like, in (default)</param>
1812
public FilterQuery(string target, string value, string operation)
1913
: base(target)
2014
{
@@ -23,8 +17,9 @@ public FilterQuery(string target, string value, string operation)
2317
}
2418

2519
public string Value { get; set; }
20+
/// <summary>
21+
/// See <see cref="FilterOperation"/>. Can also be a custom operation.
22+
/// </summary>
2623
public string Operation { get; set; }
2724
}
28-
29-
3025
}

‎src/JsonApiDotNetCore/Internal/Query/FilterQueryContext.cs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
namespace JsonApiDotNetCore.Internal.Query
44
{
5+
/// <summary>
6+
/// Wrapper class for filter queries. Provides the internals
7+
/// with metadata it needs to perform the url filter queries on the targeted dataset.
8+
/// </summary>
59
public class FilterQueryContext : BaseQueryContext<FilterQuery>
610
{
711
public FilterQueryContext(FilterQuery query) : base(query) { }

‎src/JsonApiDotNetCore/Internal/Query/PageQuery.cs

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎src/JsonApiDotNetCore/Internal/Query/SortQuery.cs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
namespace JsonApiDotNetCore.Internal.Query
22
{
33
/// <summary>
4-
/// Internal representation of the articles?sort[field] query from the URL.
4+
/// Internal representation of the raw articles?sort[field] query from the URL.
55
/// </summary>
66
public class SortQuery : BaseQuery
77
{
@@ -16,6 +16,4 @@ public SortQuery(string target, SortDirection direction)
1616
/// </summary>
1717
public SortDirection Direction { get; set; }
1818
}
19-
20-
2119
}

‎src/JsonApiDotNetCore/Internal/Query/SortQueryContext.cs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
namespace JsonApiDotNetCore.Internal.Query
22
{
3+
/// <summary>
4+
/// Wrapper class for sort queries. Provides the internals
5+
/// with metadata it needs to perform the url sort queries on the targeted dataset.
6+
/// </summary>
37
public class SortQueryContext : BaseQueryContext<SortQuery>
48
{
59
public SortQueryContext(SortQuery sortQuery) : base(sortQuery) { }

‎src/JsonApiDotNetCore/JsonApiDotNetCore.csproj

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,15 @@
4646
</ItemGroup>
4747
<ItemGroup>
4848
<Folder Include="Models\JsonApiDocuments\" />
49-
<Folder Include="QueryParameters\" />
49+
<Folder Include="QueryParameterServices\" />
5050
<Folder Include="Internal\Exceptions\" />
5151
<Folder Include="Models\Annotation\" />
5252
<Folder Include="Serialization\Common\" />
5353
<Folder Include="Serialization\Client\" />
5454
<Folder Include="Serialization\Server\" />
5555
<Folder Include="Serialization\Server\Builders\" />
56-
<Folder Include="QueryParameters\Contracts\" />
57-
<Folder Include="QueryParameters\Common\" />
56+
<Folder Include="QueryParameterServices\Contracts\" />
57+
<Folder Include="QueryParameterServices\Common\" />
5858
<Folder Include="Serialization\Server\Contracts\" />
59-
<Folder Include="Internal\Query\Raw\" />
6059
</ItemGroup>
6160
</Project>

‎src/JsonApiDotNetCore/Middleware/QueryParameterFilter.cs

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,14 @@ namespace JsonApiDotNetCore.Middleware
88
{
99
public class QueryParameterActionFilter : IAsyncActionFilter, IQueryParameterActionFilter
1010
{
11-
private readonly IQueryParser _queryParser;
12-
public QueryParameterActionFilter(IQueryParser queryParser) => _queryParser = queryParser;
11+
private readonly IQueryParameterParser _queryParser;
12+
public QueryParameterActionFilter(IQueryParameterParser queryParser) => _queryParser = queryParser;
1313

1414
public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
1515
{
16+
// gets the DisableQueryAttribute if set on the controller that is targeted by the current request.
1617
DisableQueryAttribute disabledQuery = context.Controller.GetType().GetTypeInfo().GetCustomAttribute(typeof(DisableQueryAttribute)) as DisableQueryAttribute;
18+
1719
_queryParser.Parse(context.HttpContext.Request.Query, disabledQuery);
1820
await next();
1921
}

‎src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterParser.cs

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
using JsonApiDotNetCore.Controllers;
2+
using Microsoft.AspNetCore.Http;
3+
4+
namespace JsonApiDotNetCore.Services
5+
{
6+
/// <summary>
7+
/// Responsible for populating the various service implementations of
8+
/// <see cref="IQueryParameterService"/>.
9+
/// </summary>
10+
public interface IQueryParameterParser
11+
{
12+
void Parse(IQueryCollection query, DisableQueryAttribute disabledQuery = null);
13+
}
14+
}

‎src/JsonApiDotNetCore/QueryParameters/Common/IQueryParameterService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Common/IQueryParameterService.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@ namespace JsonApiDotNetCore.Query
66
/// <summary>
77
/// Base interface that all query parameter services should inherit.
88
/// </summary>
9-
public interface IParsableQueryParameter
9+
public interface IQueryParameterService
1010
{
1111
/// <summary>
1212
/// Parses the value of the query parameter. Invoked in the middleware.
1313
/// </summary>
1414
/// <param name="queryParameter">the value of the query parameter as parsed from the url</param>
1515
void Parse(KeyValuePair<string, StringValues> queryParameter);
1616
/// <summary>
17-
/// The name of the query parameter as matched in the URL.
17+
/// The name of the query parameter as matched in the URL query string.
1818
/// </summary>
1919
string Name { get; }
2020
}

‎src/JsonApiDotNetCore/Services/QueryParser.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Common/QueryParameterParser.cs

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,23 @@
88

99
namespace JsonApiDotNetCore.Services
1010
{
11-
public class QueryParser : IQueryParser
11+
/// <inheritdoc/>
12+
public class QueryParameterParser : IQueryParameterParser
1213
{
1314
private readonly IJsonApiOptions _options;
14-
private readonly IEnumerable<IParsableQueryParameter> _queryServices;
15+
private readonly IEnumerable<IQueryParameterService> _queryServices;
1516

16-
public QueryParser(IJsonApiOptions options, IEnumerable<IParsableQueryParameter> queryServices)
17+
public QueryParameterParser(IJsonApiOptions options, IEnumerable<IQueryParameterService> queryServices)
1718
{
1819
_options = options;
1920
_queryServices = queryServices;
2021
}
2122

23+
/// <summary>
24+
/// For a query parameter in <paramref name="query"/>, calls
25+
/// the <see cref="IQueryParameterService.Parse(KeyValuePair{string, Microsoft.Extensions.Primitives.StringValues})"/>
26+
/// method of the corresponding service.
27+
/// </summary>
2228
public virtual void Parse(IQueryCollection query, DisableQueryAttribute disabled)
2329
{
2430
var disabledQuery = disabled?.QueryParams;
@@ -44,7 +50,7 @@ public virtual void Parse(IQueryCollection query, DisableQueryAttribute disabled
4450
}
4551
}
4652

47-
private bool IsDisabled(string disabledQuery, IParsableQueryParameter targetsService)
53+
private bool IsDisabled(string disabledQuery, IQueryParameterService targetsService)
4854
{
4955
if (disabledQuery == QueryParams.All.ToString("G").ToLower())
5056
return true;

‎src/JsonApiDotNetCore/QueryParameters/Common/QueryParameterService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Common/QueryParameterService.cs

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99

1010
namespace JsonApiDotNetCore.Query
1111
{
12+
/// <summary>
13+
/// Base clas for query parameters.
14+
/// </summary>
1215
public abstract class QueryParameterService
1316
{
1417
protected readonly IContextEntityProvider _contextEntityProvider;
@@ -21,8 +24,9 @@ protected QueryParameterService(IContextEntityProvider contextEntityProvider, IC
2124
}
2225

2326
protected QueryParameterService() { }
27+
2428
/// <summary>
25-
/// By default, the name is derived from the implementing type.
29+
/// Derives the name of the query parameter from the name of the implementing type.
2630
/// </summary>
2731
/// <example>
2832
/// The following query param service will match the query displayed in URL
@@ -31,16 +35,15 @@ protected QueryParameterService() { }
3135
/// </example>
3236
public virtual string Name { get { return GetParameterNameFromType(); } }
3337

34-
/// <inheritdoc/>
35-
public abstract void Parse(KeyValuePair<string, StringValues> queryParameter);
36-
37-
3838
/// <summary>
3939
/// Gets the query parameter name from the implementing class name. Trims "Service"
4040
/// from the name if present.
4141
/// </summary>
4242
private string GetParameterNameFromType() => new Regex("Service$").Replace(GetType().Name, string.Empty).ToLower();
4343

44+
/// <summary>
45+
/// Helper method for parsing query parameters into attributes
46+
/// </summary>
4447
protected AttrAttribute GetAttribute(string target, RelationshipAttribute relationship = null)
4548
{
4649
AttrAttribute attribute;
@@ -58,18 +61,20 @@ protected AttrAttribute GetAttribute(string target, RelationshipAttribute relati
5861
if (attribute == null)
5962
throw new JsonApiException(400, $"'{target}' is not a valid attribute.");
6063

61-
6264
return attribute;
6365
}
6466

67+
68+
/// <summary>
69+
/// Helper method for parsing query parameters into relationships attributes
70+
/// </summary>
6571
protected RelationshipAttribute GetRelationship(string propertyName)
6672
{
6773
if (propertyName == null) return null;
6874
var relationship = _requestResource.Relationships.FirstOrDefault(r => r.Is(propertyName));
6975
if (relationship == null)
7076
throw new JsonApiException(400, $"{propertyName} is not a valid relationship on {_requestResource.EntityName}.");
7177

72-
7378
return relationship;
7479
}
7580
}

‎src/JsonApiDotNetCore/QueryParameters/Contracts/IFilterService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/IFilterService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
namespace JsonApiDotNetCore.Query
55
{
6-
public interface IFilterService : IParsableQueryParameter
6+
public interface IFilterService : IQueryParameterService
77
{
88
List<FilterQueryContext> Get();
99
}

‎src/JsonApiDotNetCore/QueryParameters/Contracts/IIncludeService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/IIncludeService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ namespace JsonApiDotNetCore.Query
66
/// <summary>
77
/// Query service to access the inclusion chains.
88
/// </summary>
9-
public interface IIncludeService : IParsableQueryParameter
9+
public interface IIncludeService : IQueryParameterService
1010
{
1111
/// <summary>
1212
/// Gets the list of included relationships chains for the current request.

‎src/JsonApiDotNetCore/QueryParameters/Contracts/IOmitDefaultService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitDefaultService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
namespace JsonApiDotNetCore.Query
22
{
3-
public interface IOmitDefaultService : IParsableQueryParameter
3+
public interface IOmitDefaultService : IQueryParameterService
44
{
55
bool Config { get; }
66
}

‎src/JsonApiDotNetCore/QueryParameters/Contracts/IOmitNullService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/IOmitNullService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
namespace JsonApiDotNetCore.Query
22
{
3-
public interface IOmitNullService : IParsableQueryParameter
3+
public interface IOmitNullService : IQueryParameterService
44
{
55
bool Config { get; }
66
}

‎src/JsonApiDotNetCore/QueryParameters/Contracts/IPageService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/IPageService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ namespace JsonApiDotNetCore.Query
33
/// <summary>
44
/// The former page manager. Needs some work.
55
/// </summary>
6-
public interface IPageService : IParsableQueryParameter
6+
public interface IPageService : IQueryParameterService
77
{
88
/// <summary>
99
/// What the total records are for this output

‎src/JsonApiDotNetCore/QueryParameters/Contracts/ISortService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISortService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
namespace JsonApiDotNetCore.Query
55
{
6-
public interface ISortService : IParsableQueryParameter
6+
public interface ISortService : IQueryParameterService
77
{
88
List<SortQueryContext> Get();
99
}

‎src/JsonApiDotNetCore/QueryParameters/Contracts/ISparseFieldsService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/Contracts/ISparseFieldsService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ namespace JsonApiDotNetCore.Query
66
/// <summary>
77
/// Query service to access sparse field selection.
88
/// </summary>
9-
public interface ISparseFieldsService : IParsableQueryParameter
9+
public interface ISparseFieldsService : IQueryParameterService
1010
{
1111
/// <summary>
1212
/// Gets the list of targeted fields. In a relationship is supplied,

‎src/JsonApiDotNetCore/QueryParameters/FilterService.cs renamed to ‎src/JsonApiDotNetCore/QueryParameterServices/FilterService.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ public List<FilterQueryContext> Get()
2727
return _filters;
2828
}
2929

30-
public override void Parse(KeyValuePair<string, StringValues> queryParameter)
30+
public virtual void Parse(KeyValuePair<string, StringValues> queryParameter)
3131
{
3232
var queries = GetFilterQueries(queryParameter);
3333
_filters.AddRange(queries.Select(GetQueryContexts));

0 commit comments

Comments
 (0)