Public API surface #808
Public API surface #808
Conversation
Reviewed generic IEnumerable usage in public signatures (fixes 'Possible multiple enumeration' warning) Reviewed usage of generic List and Dictionary in public signatures Removed redundant ToList/ToArray/AsReadOnly calls Replaced ToList() with ToArray(), which uses a bit more memory but is faster
Moved types into separate files (and fixed filename mismatches) Unified TypeHelper and TypeExtensions (inlined methods with single usage)
…ause it does not work correctly -- it looks like something from before moving to /docs.
Removed invalid inheritdoc
Culture-sensitive string comparions
|
Is there a specific reason for not having |
|
|
|
A significant amount of types in the Startup configuration types used only once (lets come up with a better name):
|
|
I'm not sure about new
|
There is none, it slipped my mind. I'll update accordingly.
I've tried this, but the distinction is hard to make. For example,
In my opinion the whole Client serialization support should never have been added, therefore I've tried to isolate it from the JADNC library. There are better solutions in the form of language-independent support for generating client libraries using OpenAPI or C#-specific libraries for dealing with REST/JSON like RestSharp which are way better than what we provide here. If there are some types I've missed that only exist for client serialization, I'd like to move them into the Client namespace. I still keep going back and forth on whether Client should be Internal.Client instead, as it is an unfinished attempt to provide some basic support, which breaks when using JADNC advanced features like get-only properties, injected dependencies on resource classes etc. |
|
We've had some offline discussion on the client serialization and agreed to make it internal for now. The reasoning is that for server-to-server or client-to-server scenarios we can do better by exploring OpenAPI-generated client libraries in various languages, and/or explore providing extensibility points for RestSharp (which provides a lot more, such as authentication, connection resiliency, handling errors etc), because calling a json:api service involves more than just serialization (like content negotiation, query string composition and character escaping). For integration tests, I prefer to stay close to the request/response data over abstracting that away, which we do not entirely agree upon. |
Corrections in documentation after public API changes from #808
This PR is the result of reviewing the publicly exposed types and members of the JsonApiDotNetCore library and their doc-comments. Most notable change is a reorganization of namespaces.
The top-level Internal namespace is gone and has been replaced with multiple Internal sub-namespaces at deeper levels.
The meaning of Internal in the namespace path is that we preserve the right to take breaking changes there without introducing a new major version. Use at your own risk.
I also removed Contract sub-namespaces (containing only interfaces) and aimed to put them next to their implementation where possible.
New hierarchy:
Contains types related to bootstrapping and configuration in a broad sense. This includes options,
AddJsonApiandUseJsonApi, but also the resource graph, building it and various types related to dependency injection.Base classes for controllers, along with attributes to put on them.
Reusable exceptions that have a json:api functional representation, such as resource-not-found, method-not-allowed, invalid-query-string etc. Note this is not the place to collect all Exception classes. There are others which exist closely to their functional usage and are for internal use.
Mostly left as-is, this is still experimental and subject to change.
The middleware handler itself and various filters, routing conventions, formatters etc that are plugged into the ASP.NET Core request pipeline.
Contains the set of intermediate
QueryExpressionobjects that separate json:api service fromIQueryable.Contains text parser implementations (coming from query strings and resource definitions).
Contains the translation from
QueryExpressiontoIQueryable.Interfaces for handling query strings.
Implementations for handling query strings.
Repository interfaces and the EF Core-based implementation, along with some data-access related types.
The place for
IIdentifyableandResourceDefinition, along with some internals.Attributes to put on resources and their members, such as
Attr,HasOne,Links,AttrCapabilitiesetc.The root for everything related to serialization. Removed sub-namespaces for Server/Client because Server is our core business and Client is a sideways feature.
The types that take a
TResourceand produce aResourceObjectfrom it.Put existing types from Client (intended exclusively for the reverse serialization direction) here.
The set of types we feed into Newtonsoft.Json, such as
Document,Error,ResourceLinks,RelationshipEntryetc.Interfaces and implementation of the Service Layer in the JADNC architecture. Not the place to put unrelated general-purpose service classes.
After applying this new layout, there were only a handful of public types in Internal namespaces left, so I put them next to the other non-Internal namespaced types.
Due to historic reasons, nearly all classes have always been public which may not be appropriate. I did not review those.
Fixes #734
Fixes #567