Support for generic request meta

[jfhs]

Currently the only (documented) way to add metadata is to implement IHasMeta in entity class. However, it might be good to have some generic way to add it to any request, regardless of the entity type, i.e. for pagination, performance metrics or some caching information.

I am not sure what would be the right place to have it, maybe as an option for DocumentBuilder somehow?

[jaredcnance]

What do you think about adding it to JsonApiOptions? It would then be set in the ConfigureServices hook like so:

services.AddJsonApi<AppDbContext>(opt =>
{
    opt.DocumentMeta = new Dictionary<string, object> {
       { "key", "value" }
    }
});

As far as pagination goes, that should already be taken care of here. Is there additional information you think might be desired?

In regards to being able to include request specific information, how would you envision the user implementing it? Off the top of my head, I could see an interface (defined by this library) that could be implemented by an application service and it could be injected into the JsonApiContext. Maybe something like:

public interface IRequestMeta
{
    Dictionary<string, object> GetMeta();
}

public class MetaService : IRequestMeta
{
    private IHttpContextAccessor _httpContextAccessor;
    public MetaService(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }
    public Dictionary<string, object> GetMeta() {
        // build the meta object
    }
}

public JsonApiContext(/* ... */,  IRequestMeta requestMeta)
{
    // ...
    RequestMeta = requestMeta.GetMeta();
}

The DocumentBuilder could combine the JsonApiContext.RequestMeta with the Options.DocumentMeta and resource level IHasMeta.

[jfhs]

I think there is no need to have two different ways of adding generic meta (options and MetaService), just having MetaService should be enough, because one can always add static meta in MetaService as you proposed with options.

Regarding pagination, I believe that is fully up to user what fields there should be. In my particular case I used previously following pagination meta:

{
  "page": {
    "from":1,
    "to":1,
    "total":1,
    "per-page":10,
    "current-page":1,
    "last-page":1
  }
}

But I am sure everyone have different needs/naming conventions, that's why I think having an ability to have generic metadata generator would be useful.

Your proposal about IRequestMeta looks good to me.

[jaredcnance]

Good points. I wonder if, instead of setting the request meta in the JsonApiContext constructor, if it would be better to have a hook in the middleware AFTER the MVC middleware. In your pagination example, there's no way the application would have any knowledge of the paging information yet since it won't happen until after the controller is resolved. If we add a hook after the MVC middleware, all of the request/response information should be available:

public static IApplicationBuilder UseJsonApi(this IApplicationBuilder app)
{
    app.UseMiddleware<RequestMiddleware>();

    app.UseMvc();

     // add something like this (would love a better name than this): 
    app.UseMiddleware<PostRequestMiddleware>();

    return app;
}

PostRequestMiddleware might look like:

public async Task Invoke(HttpContext context)
{
    var context = context.RequestServices.GetService<IJsonApiContext>();
    var requestMeta = context.RequestServices.GetService<IRequestMeta>();
    context.RequestMeta = requestMeta.GetMeta();
}

[jfhs]

I didn't notice that you retrieve meta in the constructor, I thought it was called in Builder (at which point most of the data is available).

I think that's a good idea with hook, because it is clear when it's invoked, and it doesn't add dependency to DocumentBuilder so in future this RequestMeta can come from somewhere else.