Building Enterprise Grade Web APIs - Use Feature Folders

One of the most important attributes of any code we write is maintainability.  Over the lifetime of a piece of code, it will be debugged, modified and upgraded numerous times, often by developers who were not on the original team that wrote the code. 

One of the most important aspects of maintainability is that the developer maintaining the code needs to be able to easily find what they are looking for.  This is where feature folders come in.  When using feature folders in our API, we don't use the traditional folders named Models and Controllers.  Instead, we name our folders after the endpoints of our API (the features) and place all the code related to to that endpoint (feature) within that folder.  Here is an example:

As you have probably guessed, this is an API related to Food Trucks.  If you looked at the endpoints for the API you would see URLs like /api/FoodTrucks and /api/Locations.  It is pretty easy to guess where the code is for those endpoints, in the FoodTrucks and Locations folders respectively.  For child endpoints, that is, endpoints like /api/FoodTrucks/{foodTruckId}/Reviews, I use a dot notation on the folder name like FoodTrucks.Reviews.  As you can see though, it is very easy to map from what an endpoint is to where the code is that supports that endpoint.

As you see in the screenshot above, I have expanded the Locations folder so we can have a look inside.  We see the following:

• The controller - LocationsController
• The view models used by this feature - LocationModel, CreateLocationModel and UpdateLocationModel
• Two validator classes that are used to implement validation rules related to this feature  - CreateLocationModelValidator and UpdateLocationModelValidator
• The AutoMapper profile used to map objects related to this feature - LocationsAutoMapperProfile.

Without even looking inside the files at the code, you already have a pretty good idea about what is going on.  And you know where everything is related to this feature.  Contrast this with the traditional folder layout in MVC projects:

Here if we need to debug and then make a change to the Locations endpoint, we have to navigate multiple folders to do so.  In fact, I'm not even showing the validator classes or the AutoMapper profile classes in this screenshot because they don't fit on the screen.  Sure, we could put our validators in with our models in the ApiModels folder, but for even for this relatively API, we are starting to get some folders that are unwieldy.

There is another benefit of using feature folders.  Since all of the code used for a feature is in one folder, the folder (and thereby the namespace) forms a boundary in our code that delineates this feature.   If we find ourselves needing to reach across folders, we are crossing a boundary in our code base and we have an indication that something is wrong.  This helps to discourage us from sharing model objects across two or more controllers where the object would have more than one responsibility.  Having boundaries defined like this in our code helps us be more modular and keep everything where it belongs.

Summary

I think feature folders are the way to go.  This is a pattern that you actually see quite a bit in the Angular and React communities, and I think there is no reason not to adopt the same in ASP.NET projects.  I think we end up with a much cleaner organization of the code and it is easier to find what you are looking for.  So for your next project, give feature folders a try.  I think once you complete a project using feature folders you will agree it is the way to go.