v4.0.2

Fixes a NullReferenceException when using resource hooks.

Closed issues

Open up some members for extensibility (#927)
Fix for OnReturn hook in GetSecondary pipeline (#924)

v4.0.1

This version lowers the minimum required version of EF Core from 3.1.10 to 3.1.0.

Closed issues

• Dependency on 3.1.10 of EF Core (#913)

v4.0.0

Introduction

We're back! Almost 2 years since the last stable release, a lot has changed.
The original author was no longer able to maintain the project.
Long story short: @bart-degreed and @maurei have taken over and are fully committed to bringing this project to the next level.

Are you building an API from scratch? Our documentation is the place to get started.
Upgrading from v3 instead? Be sure to check out our migration guide.

The release notes of earlier pre-release v4 versions contain detailed lists of changes since v3. To summarize, these are the highlights:

• Works with .NET Core 3.1/5 and Entity Framework Core 3.1/5
• New advanced filtering capabilities (old syntax is still available)
• Enhanced support for usage of the existing query string parameters
• Flexible annotations to control what is permitted per resource attribute
• Increased compliance with the JSON:API specification
• Improved handling of create/update/delete of resources and relationships
• Added support for POST and DELETE on relationship endpoints
• Change tracking on POST/PATCH requests reduces the size of response messages
• Vastly improved request validation with clear error messages
• Built for scale: default page size, options to control maximum page size and number, maximum include depth
• Improved support for custom logging and error handling
• Eager Loading enables to unconditionally include unexposed related entities
• A limited set of services can now be injected in resources
• Up-to-date documentation, including auto-generated examples
• SourceLink enables to step into our NuGet library during debug by downloading sources from GitHub
• Well over a thousand automated tests (mostly integration)
• Lots and lots of bugfixes

Removed features:

• Entity-Resource separation (motivation here).
• Bulk operations, because json:api has retracted its experimental specification.
  As a replacement, they recently finished Atomic Operations, which we intend to implement in one of the next versions.

Finally, a big thanks to all community contributors!

Release notes

New features

(none)

Breaking changes

• Changed the usage of fields query string parameter to be json:api spec compliant. It now requires a resource type between brackets instead of a relationship path. The value can contain both attributes and relationships.

Closed issues

• Small refactorings (#893)
• Changes usage of fields parameter to be json:api spec compliant (#904)
• Fixed: hide duplicate stacktrace for ModelState errors (#905)
• Fixed: write content type on invalid Accept headers (#903)
• Wrong totalResourceCount when using resource definition filter (#881)
• Minor fixes in content negotiation (#897)
• Refactored JsonApiException to contain a list of errors (#894)

v4.0.0-rc

New features

• When a request is canceled, we propagate that down to EF Core (#879)
• New extension method AddResourceRepository() on IServiceCollection, similar to AddResourceService() (#875)
• Added POST/DELETE endpoints for to-many relationships (#875)
• Detection of side-effects during PATCH request now also runs on POST (#875)
• Improved error messages for malformed request bodies (#875)
• Resource-specific meta (#845)
• Best-effort paging (when total count is unknown) (#840)
• Generic resource definitions (#832)

Breaking changes

• We used to return 200 OK with { data: null } for PATCH requests without side effects, where we now return 204 No Content without a body
• Changed how custom meta is registered (see #737 (comment) for details)
• Base class ResourceDefinition was renamed to JsonApiResourceDefinition and the meaning of IResourceDefinition was changed.
• IsRequiredAttribute was added in v4-beta1 to enable ASP.NET ModelState validation of partial PATCH requests. This attribute is no longer needed and has been removed. Use the built-in RequiredAttribute instead.
• Breakup of AttrCapabilities.AllowChange (affected both POST and PATCH) into AttrCapabilities.AllowCreate (only POST) and AttrCapabilities.AllowChange (only PATCH)
• When page size and/or number match their default value, we no longer include them in paging links.

Closed issues

• Restructured eager loading tests and fixed two bugs (#882)
• Fixed: Paging links should not be rendered in POST response (#880)
• Add cancellation support (#878)
• Support POST requests to a to-many relationship link (#353)
• Support DELETE requests to a to-many relationship link (#850)
• Patching resource relationship on primary endpoint with non-existing resource fails (#852)
• Implicit removes and FK constraint violations on PATCH relationship endpoint (#853)
• Response when updating relationship of resource not conform spec (#578)
• PATCH Successfully but Return Data is Null (#870)
• Support for Self-Referencing ManyToMany Relationships (#790)
• Potential Bug Serializing Id's? (#363)
• Allow classes which inherit from DefaultResourceRepository more control of SaveChangesAsync (#690)
• Many-to-many includes no longer work on v4.0.0-beta1 (#868)
• Optimized/fixed TypeLocator.GetGenericInterfaceImplementation (#857)
• How to deserialize a class with a relationship that is a derived class? (#696)
• IHasMeta does not work (#737)
• Injecting multiple DbContexts does not work (#739)
• Feature: provide best-effort paging links when total count is unknown (#791)
• Bug: custom query string parameters do not respect casing convention (#719)
• Generic resource definitions (#806)
• Improved ModelState validation (#834)
• Fixed: Relations being validated on POST (#671)
• Add AttrCapabilities.AllowCreate (#801)
• Do not render defaults in paging links (#817)
• Fixed: Invalid parsing of legacy query strings (#815)
• Fixed: Type match incorrect for PATCH requests (#789)

v4.0.0-beta1

New features

• Composable filters and deeply nested queries (see #792 for details)

Breaking changes

• We no longer call app.UseRouting() and app.UseEndpoints(...) anymore, so you need to add these yourself to Startup.cs
• Code namespace changes (details at #808)
• New filter query string syntax. Set options.EnableLegacyFilterNotation to true to allow legacy filters
  To use new notation, prefix with "expr:", for example: ?filter=expr:equals(lastName,'Smith')
• Multiple filters in query string at same depth are combined using OR operator (used to be AND, which violates json:api recommendations)
• Using a negative page number (to reverse order) is no longer possible
• "total-records" in response meta has been renamed to "total-resources" (and casing convention is applied)
• ResourceDefinition<T>.HideFields() has been replaced by ResourceDefinition<T>.OnApplySparseFieldSet()
• ResourceDefinition<T>.GetQueryFilters() has been replaced by ResourceDefinition<T>.OnRegisterQueryableHandlersForQueryStringParameters
  These are no longer tied to only filters. For example: ?filter[isHighRisk]=true now uses: ?isHighRisk=true
• When no sort is provided, resources are sorted ascending by ID
• Notable renames:
  DefaultResourceService -> JsonApiResourceService
DefaultResourceRepository -> EntityFrameworkCoreRepository
BaseJsonApiController.GetRelationshipsAsync -> GetRelationshipAsync
BaseJsonApiController.GetRelationshipAsync -> GetSecondaryAsync
AttrCapabilities.AllowMutate -> AllowChange
• Most occurrences of 'entity' were renamed to 'resource' and Default prefix was removed from various class names

Closed issues

• Routing does not respect custom pluralized resource name (#805)
• Changes on public API surface (#808)
• Fixed versioning on AppVeyor NuGet feed (#802)
• fix: support for lazy loading proxies (#793)
• Composable filters and deeply nested queries (#792)
• Required Input validation disabled for partial patching / relationships (#781)
• Fix synchronous error in flushasync (#773)
• Fixed: only run custom path cutting logic when RouteAttribute is used (#769)
• Fixed: Namespace not honored when RelativeLinks=true (#763)
• Simplified signature of app.UseJsonApi() (#750)
• Fixed: exception logged in Kestrel on Delete request (#762)
• Show helpful error when ActionResult returns unsupported type (#753)
• Fixed: Filter passes query validation, but the filter is not applied (#659)
• Simplify/optimize filter query string parsing (#758)
• Unexpected behavior on negative page number (#757)
• Fixed: error setting default sort for non-string properties (#754)
• Fixed: sorting on multiple attributes (#755)
• Fixed: do not intercept exceptions thrown from non-json:api requests (#749)
• Fix for GetDefaultSortOrder not firing (#746)
• Fixed: missing property setter in options (#742)

Special thanks to @bjornharrtell and @fdlane for providing feedback, trying things out, submitting bugs or even fixing them!

v4.0.0-alpha5

New features

• Configurable default attribute capabilities in options.
• Resources are found from DbContext.Model (no more need to expose them via DbSet<> properties).
• Inject services in entities (see limitations at https://docs.microsoft.com/en-us/ef/core/modeling/constructors#injecting-services).
• Return updated resource from PATCH only if the update changes the resource in ways other than those specified by the request.
• SourceLink: enables to step into the NuGet library by downloading sources from GitHub.
• Improved support for custom logging and error handling.
• Eager loading: unconditionally include unexposed related entities.
• Overloads on app.UseJsonApi() to influence middleware order.
• New options to constrain maximum page size and number.

Breaking changes

• Paging is now enabled by default. Set options.DefaultPageSize = 0 in Startup for the old behavior.
• Query string parameters omitNull/omitDefault have been renamed to nulls/defaults and the meaning of their true/false values is inverted.
• Casing convention is set in options using Newtonsoft.Json.Serialization.NamingStrategy.
• Some types were renamed, had signature changes and/or moved into different namespaces.
• ILoggerFactory is no longer optional. Use NullLoggerFactory.Instance from tests.
• Replaced set of optional booleans on Attr with flags enumeration.
• Content negotiation returns 406 to browsers that send incompatible Accept headers.

Closed issues

• Default attribute capabilities (#707)
• Fixed: Re-fetch entity after CREATE without relationships (#724)
• Fixes in content negotiation, better separation between json:api and asp.net controllers (#725)
• Bugfixes on combining sparse fieldsets with includes (#708)
• Fail on mismatch between ID in URL and patch body (#702)
• Use EF Core entity model when scanning for resources (#550)
• Added support for injecting DbContext in resources (#657)
• Fixed NullReferenceException on parallel requests (#727)
• Use NamingStrategy from Newtonsoft.Json to configure casing convention (#718)
• Fixed: custom serializer settings are ignored (#687)
• Fixed: crash on invalid relationship name (#713)
• Replaced omitNull/omitDefault query string parameters with nulls/defaults (#720)
• Change tracking for patch updates, to improve json:api spec compliance (#577)
• Fixed: run tests in parallel (#485)
• Restored SourceLink support (#692)
• Fixed: null data returned when resource not found (#631)
• Fixed: crash on invalid relationship name (#709)
• Improved and pluggable error handling and logging (#714)
• Improved request validation (#655)
• Eager loading: unconditionally include unexposed related entities (#652)
• Include query string parameters in top-level self link and paging links (#276)
• Fixed: Filtering on special chars sends back an un-escaped special character in the links urls (#408)
• Updated to .NET Core 3.1 (#711)
• Fixed inefficient cache usage (#450)
• Cleanup of public overloads for ILoggerFactory (#674)
• Added MaximumPageSize and MaximumPageNumber to IJsonApiOptions (#673)
• Allow user flexibility in authentication/authorization middleware options (#656)
• Fixed invalid top-level self link (#646)
• Expose DefaultPageSize/RequestedPageSize to give the user more control over pagination (#641)
• Support query param operations on nested resources (#634)
• Fixed: first/prev links not rendered on second page (#622)

v4.0.0-alpha4

Version v4 is now feature-freezed. We will need some time to

• create a migration guide for those coming from v3.1
• update the docs and example projects

In the meanwhile we will beta (battle) testing this version in our own applications.

• Fix a NullReferenceException when a 404 is returned (#620)
• Fix/deviating dbset name (#603)
• Fix/pagesize (#601)
• fix: typo LoaDatabaseValues (#608)
• Acceptance tests EF inheritance (#610)
• Improve usability RequestSerializer (#613)
• Move EF core related building to extension methods (#616)
• Hooks discovery detection of implemented hooks issue (#617)
• feat: use camelCase as default (#618)
• Simplify DefaultResourceService constructor (#592)
• Upgrade to .net core 3.0 (pr #595 issue (#559) (with great contributions of @wisepotato)
• Fix DiscoveryTests and NoEntityFrameworkExample project/tests (#590)
• Renaming and consistency (#589)
• Separation of concerns ResourceGraph (#586)
• Use relationships as navigations in sparse field queries (#584)
• Allow for multiple naming conventions (camelCase vs kebab-case) (#581)
• New constructor overload in query controllers (#580)
• Cleanup of repository layer (#579)
• Query parameter services (#574)
• (Temporary) removal of bulk and split (#571)
• Serialization wiki (#561)
• Serializer decoupling (#558)
• Context decoupling (#557)

v4.0.0-alpha3

Breaking changes:

#520: Patch requests where the payload does not include the id(s) of the target resource(s) is no longer accepted.
#519: UpdateAsync(TId id, TEnity entity) was replaced with UpdateAsync(TEnity entity)
#478: RelationshipAttribute.Type was replaced with RelationshipAttribute.DependentType
#478: EntityResourceService constructor EntityResourceService(IJsonApiContext, IEntityRepository<TEntity, TId>, ILoggerFactory, loggerFactory, IResourceMapper ) was deprecated and replaced with EntityResourceService(IJsonApiContext, IEntityRepository<TEntity, TId>, IResourceHookExecutor = null, IResourceMapper mapper = null, ILoggerFactory = null)

Bug fixes / clean up

#522 An issue with deserializing timespans was fixed. Thanks to @ngboardway!
#518: The DefaultEntityRepository has had a major cleanup. Thanks to @wisepotato for reviewing!

• problems errors of with entities being attached to the DbContext with the usage of hooks and custom services has been fixed
• changes done to entity in a custom service before calling the old UpdateAsync(TId id, TEnity entity) repository method were not actually saved to the database.
• Progress was made to decouple IJsonApiContext (see #512) from the repository layer by removing usage of HasOnePointers and HasManyPointers.

New features

#502 support for "implicit removal" of relationships
#478 Resource Hooks, see the usage guide for detailed description. Thanks @wisepotato, @milosloub and @jaredcnance for extensive reviewing!

v4.0.0-alpha2

Breaking changes

#513 Revert back from new GetQueryable() to Get() in DefaultEntityRepository. Difference between v3.1.0 and v4.0.0-alpha2 is order of Select method call, which is responsible for sparse fields resolve.

If sparse fields are requested:

Old way in 3.1.: EntityResourceService.GetAsync() calls DefaultEntityRepository.Get().Select() -> this limits selected columns in the begining and filters stops working for atributes that are not requested in fields!

New way in 4.0: EntityResourceService.GetAsync() calls pure DefaultEntityRepository.Get(), Select() is separated and resolved in EntityResourceService.GetAsync() after get, include, filter and sort operations. This solution provides correct SQL translation and functional sparse fields system!

v4.0.0-alpha1

Breaking changes:

#476 and #498 Sparse fields set not applied to query correctly. Thanks @maurei for cooperation !
#482 Increase ResourceDefinition GetFilterQuery Flexibility. Thanks @joshhubers !

Bug fixes:

#492 Update one-to-many through PATCH on resource not working. Thanks @maurei !
#494 Update many-to-many through PATCH on resource not working. Thanks @maurei !
#509 DateTimeOffset is modified during deserialization.

Description fixes/improvements:

#481 Fix typo in controller. Thanks @diegobrum !
#487 added explanation for ValidateModelState option. Thanks @CoolGoose !
#489 and #490 fixed descriptions. Thanks @fdlane !