Expand IMaterializer interface to handle more of what's in ApiController

[SphtKr]

The question was raised in #31 whether we can pull some of what's done in JSONAPI.EntityFramework.Http.ApiController into IMaterializer methods, and possibly collapse the two ApiControllers into one more general one, leaving the implementation specifics in IMaterializers. This probably makes sense because the existing EF ApiController verb methods are hard to reuse as is, and see also #35.

[csantero]

I would say that IMaterializer should have one method to correspond to each API endpoint we want to expose. Then the ApiController<> can just proxy those calls. We might also want to make IMaterializer generic. So an ApiController<Post> would need to be provided with an IMaterializer<Post>. Then we could remove the non-generic methods, and shift the generic type parameter from the methods to the interface.

[SphtKr]

Hmm. Another way of looking at this is to create a proxy object for ApiController instead of subclassing ApiController...and move the generic traits from our ApiController subclass(es) to another class. I rephrase it this way because I'm not sure that IMaterializer is the place that these methods should go, so to accomplish what you're saying we may need to put something else in between IMaterializer and ApiController.

Or maybe not, I'll have to think about this.

At present IMaterializer's role is far more specific. It was particularly created to address two main problems, and especially for the case of Entity Framework:

1. Building the object graph of a POST (especially, but also PUT) with related objects identified by id only. Since JsonApiFormatter has no knowledge of the persistence layer, the best it can do when presented with an array of related IDs is create a set of dummy objects each with its ID properly set. But you can't save the POSTed object like that of course, so EntityFrameworkMaterializer fleshes out the dummy objects, replacing them with actual entities retrieved from a DbContext. This is the primary reason for the GetById method in IMaterializer, then I used it for the Get method just because it was already there.
2. The problems of resolving Put payloads into Entity Framework entities (which to be efficient, had to only update those properties which had changed) and also deal with the spec allowing for underposting only changed values:

To update one or more attributes of a resource, the primary resource object should include only the attributes to be updated. Attributes omitted from the resource object should not be updated.

Thus there is all the code in EntityFrameworkMaterializer to explicitly loop through the properties on an object and only set those values which are changed values. Thus also there is no more general IMaterializer implementation in the JSONAPI namespace because it is unknown whether such an approach (setting properties one by one) is important to another persistence layer (or lack thereof). In some applications, an IMaterializer may not even be needed, as the plain deserialized object may be sufficient.

The other complicating factor was Entity Framework's concept of a DbContext, which is not just an abstraction of the DB connection, but is also a "unit of work" pattern...i.e., if I materialize a PUT, the object I materialize has to be retrieved from the same context as the objects in its associations, and furthermore if the user's application logic needs to add more objects to any associations it has to have access to the same context as well (hence the DbContext property accessible on the EntityFrameworkMaterializer.

So, I'm not yet sure whether IMaterializer should remain a separate object with its own role or should take on more responsibility internally.

[csantero]

Makes sense. Sounds like the best way to move forward is to add that generic proxy interface (maybe call it IRepository or IUnitOfWork?). What is currently done by the EntityFrameworkApiController can be moved into our default implementation of that interface.

Our ApiController could then be ungenericized, and its methods would simply echo those on the proxy. It would have a way for the user to provide the proxy, either with a virtual factory method or using DI.

[csantero]

Or maybe IApiService

[SphtKr]

Yeah, perhaps IRepository, but we'll probably have to wait and try it to see whether the API comes out more like HTTP verbs or more like CRUD methods. After 0.3.0 is frozen we may want to create a branch to try this out, it could get messy.