Sunday, December 28, 2014

Using Web API 2 with Entity Framework 6

I feel that the most difficult part of starting a new project is deciding what technologies to use.  Over the last several months I've been working with Web API 2 & EF 6 to create a REST service for use with a WPF application that I've been writing.  Here I'd like to detail the reasons I chose this technology combination and some of the lessons I've learned along the way.
  • The testing story is improved with EF6 DbSet<T>
  • Had used EF4 & EF5 on other projects
  • Web API has OWIN (Open Web Interface for .NET) allowing it to run locally without a web server
  • Web API is fairly straightforward in concept being based on the HTTP verbs GET,POST,PUT,DELETE.
  • Both Microsoft Technologies with lots of information floating around the web
Looking back of the last few months, I've had very little trouble with Web API 2. It has been pleasant to work with.  The majority of my issues have been with Entity Framework.  This may be due to how I chose to use the technology though I haven't done anything that radical.
The basic structure of my project followed the aggregate root concept.  Our application is basically a giant calculator, taking several input parameters and returning a calculation.  For example, when a project entity is loaded, I want to load all of its child entities otherwise I don't have the data needed for a calculation.
(AR) Fluid - Polymorphic type
        -int Id
        -string Name
        -List<FluidPointBase> FluidPoints - Polymorphic list of items
(AR) Material
        -int Id
        -string Name
        -double Density
(AR) Project
        -int Id
        -Fluid Fluid
             -int Id
             -string Name
             -List<FLuidPointBase> FluidPoints
         -Material Material
             -int Id
             -string Name
             -double Density
Testing Controllers
There is a heated debate on StackOverflow and elsewhere regarding the question of whether one should use the repository pattern or forgo it in favor of mocking the methods on the underlying ORM.  I was swayed by the argument that in EF it is possible to create testable code without a repository.  Following the patterns described below I was able to set up tests for my controllers.

  • Entity Framework 6 now has a very easy to mock implementation of DbSet<>, this technically makes it possible to test against EF, without the Repository or UOW patterns. These patterns take time to code, and maintain, and add another layer to the application.
  • Response in Web API 2 should be of type IHttpActionResult this will allow for easier testing.
  • Fiddler - HTTP debugger
Web API Considerations
I soon found that there are many things to consider when building a Web API service. 

  • What are REST best practices?
  • Does it need to be truly RESTful? If so add HATEOS
  • HATEOS (Hypermedia as the Engine of Application State)
  • Provide links when doing operations such as
  • Creating new content
  • Updating content
  • Navigation for paging
  • Can be in the form of url, rel, and method(get,post,put,delete)
  • HAL (Hypertext Application Language) & Collection + JSON are current standards
  • Will the API be public? 
  • Versioning of Web API's is important for consumer compatibility
  • CORS - Cross origin resource sharing 
  • Modern browsers support this, and there is support for it in web api2
  • No need to support JSONP if you don't need it because of CORS
  • How to handle paging?
  • Use a class as a data envelope for paging
  • Include pagination information in the header
  • Optimistic Concurrency in Web API 
  • How to handle polymorphic type serialization with JSON?
  • REST & JSON polymorphic types seem to fly in the face of REST best practices, probably not a good idea to use them on a public API.
  • Requires configuring the JSON Formatter to enable type name handling in the Web API configuration.
  • config.Formatters.JsonFormatter.SerializerSettings.TypeNameHandling = Newtonsoft.Json.TypeNameHandling.All;
Entity Framework Pain Points
Most of my gripes are with EF.  As I've worked on this project, EF has been an unending source of issues.  

  • No eager loading of polymorphic types 
  • This means you either have to explicitly load each derived type, or rely on lazy loading.
  • Table per Type (TPT) inheritance breaks cascade delete
  • Makes you feel crazy when the fluent API is configured correctly and your keep getting reference constraint errors!
  • Workaround by executing Sql in seed method
  • The worst thing ever - NO GRAPH MERGING FOR DISCONNECTED ENTITIES
  • At first I manually wrote the logic to merge the graph, I got depressed writing books of code and thankfully found GraphDiff.
Without GraphDiff the update logic for one related graph in an entity would look something like this...

                // Update scalar/complex properties of parent
                TheContext.Entry(currentWell).CurrentValues.SetValues(entity);
               // Updated related geometry items
                var geometryItemsInDb = currentWell.Geometries.ToList();
                foreach ( var geometryInDb in geometryItemsInDb)
                {
                    // Is the geometry item still there?
                    var geometry = entity.Geometries.SingleOrDefault(i => i.Id == geometryInDb.Id);
                    if (geometry != null)
                        // Yes: Update scalar/complex properties of child
                        TheContext.Entry(geometryInDb).CurrentValues.SetValues(geometry);
                    else
                        // No: Delete it
                        TheContext.WellGeometryItems.Remove(geometryInDb);
                }
                foreach ( var geometry in entity.Geometries)
                {
                    // Is the child NOT in DB?
                    if (geometryItemsInDb.All(i => i.Id != geometry.Id))
                        // Yes: Add it as a new child
                        currentWell.Geometries.Add(geometry);
                }
With GraphDiff updating an entire graph looks like this....
//Note: GraphDiffUpdateGraph is a virtual method for mocking...  Actual method with GraphDiff is UpdateGraph()
TfContext.GraphDiffUpdateGraph(entity, f => f.OwnedCollection(p => p.Geometries)
                                                         .OwnedCollection(p => p.SurveyPoints)
                                                         .OwnedCollection(p => p.Temperatures));
Decisions for my API

  • Choose to include HATEOS in the API - though in retrospect this may have been a YAGNI violation. 
  • Used Polymorphic types, this increases the size of the JSON payload and is likely not a REST best practice
  • Used lazy loading in EF to avoid explicitly loading derived types
  • Wrapped DbContext methods such as Entry() and UpdateGraph() to make them mockable
  • Used an object for paging instead of passing the page information in the header

Conclusion
There are several things that are still unresolved in my mind.  RESTful API's by their very nature seem to be in conflict with the Aggregate Root concept.
Do I have an API where I hit the endpoint Project/1 and get back my Project object with all its data or do I hit get back a Project, with a link to a Fluid entity and a link to a material entity?  What about polymorphism?  If I get rid of my polymorphism in the entities, doesn't that increase the number of controllers I'll need to serve the API?
Obviously there is still much to be learned...


Wednesday, December 3, 2014

Web API 2 - Using [FromUri] with GET Methods

Web API 2 has the default route specified as:

     webApiConfig.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
                );

However, consider the following two GET method signatures.

   public async Task<IHttpActionResult> GetAsync(int id);
   public async Task<IHttpActionResult> GetAsync(int page, int pageSize);

Web API first does route template matching, and then it selects the method.   Based on that, these GET methods would map like this...

api/controller                              (matches route, can't find a method as all require parameters)
api/controller/1                           (matches route, get's resource with Id = 1)
api/controller/1/10                      (matches route, get's paged data)

What I really wanted was to be able to specify a route with query string parameters...  In Web-API query string parameters get bound to parameters of the same name in the controller actions, so I could also call my GetAsync(int page, int pageSize); method as follows.

api/controller?page=1&pageSize=10

That's great but without default values, the route to the resource at api/controller is still going to return this message. "The requested resource does not support http method 'GET'."
The first thought that occurred to me was to make the page and pageSize parameters optional.

public async Task<IHttpActionResult> GetAsync(int page=1, int pageSize=10);

However, this makes the methods indistinguishable from one another.  That lead me to look for another way to pass multiple parameters to my Get method. This is where the [FromUri] attribute comes into play.  Essentially it works much like the [FromBody] attribute used with Put & Post methods. Using [FromUri] specifies that we are going to use data passed in the Url to build up our object.  


The result is the following code.  Inspired by this code...