ardalis

Steve Smith, software craftsman

Connect with me:

Your API and View Models Should Not Reference Domain Models

17 Comments

Your API and View Models Should Not Reference Domain Models

If you’re organizing your application following Clean Architecture and Domain-Driven Design, with your Core domain model in one project that is referenced by your UI and Infrastructure projects, you should be careful what you expose in your client-facing models. Client facing models typically reside in the UI layer as ViewModels or ApiModels, or they may be called DTOs (Data Transfer Objects). In any event, they should not directly reference types from your domain model, which will consist primarily of entities and value objects (see DDD Fundamentals for more on these concepts). Learn more about kinds of models here.

Why shouldn’t DTOs and related types reference domain model entities?

To answer this question, let’s back up and talk about why we’re using DTOs and ViewModels/ApiModels in the first place. Why should we have multiple types for describing what is probably the same thing in our system? For instance, let’s say I have a website where users can come and take tests. Each test has a name, a description, and a collection of questions. My domain model for the test includes some business logic for things like ensuring there is at least one question, that there aren’t duplicate questions, that the name follows a particular convention, etc.

Now in my web project, I need a way for an admin user to add a new test to the system, or update one that already exists. When they do so, I don’t necessarily want to let them touch every single property of the test. For example, maybe I only want the user to create a test with a name and description, and when they do an update maybe the name is immutable but they can add or remove questions or update the description. Depending on whether I’m letting the user perform this work using plain MVC or via an API, I will create ViewModel or ApiModel types that map to the operations the user can perform. If they’re going to be able to create a new test with just a name, I might have class like this one:

My actual domain entity for a Test might look more like this, though:

What if instead of writing my action method to accept a CreateTestViewModel, I skipped that and just accepted a Test? Well, then end users could potentially access the full state of the Test entity. Model binding will map whatever JSON or Form data the user sends into my model type. My form or my published API documentation might say that only the Name and Description should be passed in, but a malicious user might be able to guess at my underlying model and realize they can also create Authors (or modify things on Authors, like their roles) and Exercises. If the server-side code isn’t written carefully, it might silently accept whatever the user sends and then persist it to the data store using simple EF commands like Add() and SaveChanges().

If you’re writing API code and you want to help out your end users by giving them useful, live documentation on your API, look at Swagger and related tools. Using Swagger, you can support an endpoint on your web application that will provide an interactive view of all of your public API endpoints and their expected data signatures. By using separate API models, you can ensure that your API is as simple as possible, making your consumers’ lives easier. You can also cut down on how much data you send over the wire, improving performance and saving money on bandwidth by ensuring your API models are as lean as possible.

Another reason to avoid referencing domain model types from your DTOs and ViewModels/APIModels is serialization. It’s not unusual to lock down domain model types by giving them private constructors and pulling in required fields through constructors. This is especially true for immutable value objects, which should always take in their state at construction time. If you try to use these types as your wire protocol for APIs or MVC model binding, you’re likely to run into problems with deserialization, since the types lack a default public constructor. Using models dedicated to your front end once again avoids this issue.

Tip: Look at Using Statements

The simplest way to avoid having your domain model seep into your wire protocol types is to look at the using statements for these classes:

Often, domain model references end up in your DTOs because they’re added as properties. Make sure your property data types are, themselves, DTOs (or ViewModels or ApiModels, etc.). Watch for having your Core.Entites or similar namespace being used in your DTO class definitions. You can just look for this during code reviews, pull requests, etc., or you can create a rule in a tool like NDepend that will warn you if such a reference is found in classes that match a certain naming convention or belong to a particular namespace.

 

  • Aaron P. Olds

    I was just explaining this to one of my junior developers. So I posted this post on his slack channel. Thanks!
    Another useful tool when dealing with domain model -> DTOs and DTOs -> domain model is AutoMapper. This has saved me a ton of work!

    • ardalis

      Yes, AutoMapper is a great tool!

  • Kevin Kuebler

    Hey Steve, good advice!

    How do you handle creating your ViewModel/ApiModel instances? Do you just use AutoMapper as Aaron mentioned? We’re not currently using it (although maybe we should take a closer look at it). Often our ViewModels/DTOs require a bit of logic to construct – it’s usually not just a bunch of simple property->property mapping.

    So we often will put static factory methods on the ViewModel type which take in an instance of the domain model class (or classes) needed to create that ViewModel. So, using your example in the post, we’d have something like: CreateTestViewModel.FromTest(Test test). Which would encapsulate the logic necessary to create the ViewModel instance and map the data from the domain object.

    This works well, and I feel is cleaner/simpler than having a bunch of separate factory classes. It does require having the namespace imported in the ViewModel class file though. Which could lead to the mistake we’re trying to avoid of including a type from the domain in the ViewModel type itself. (Well, I guess it’s not required, we could just fully qualify the namespace in the factory method).

    • ardalis

      Someone just asked me something similar on twitter:
      https://twitter.com/spetryjohnson/status/915581052546162689

      I’ll start with just a LINQ statement doing the mapping, as in:
      var storeDTOs = GetStoreEntities().Select(s => new StoreDTO()); // perform mapping inside .Select

      I usually do the static factory method approach as a second step, like:

      public class StoreDTO {
      // some properties

      public static StoreDTO FromStore(Store store)
      {
      // map from store entity to a new DTO and return it
      }
      }

      This is eliminates duplication in your .Select statements, and you can update the .Select to just say (s => StoreDTO.FromStore(s)).

      But then you have these ugly, repetitive static factory methods. So you usually end up using a tool like AutoMapper to do away with those, and you’re left with just the need to DI a mapper instance into your services or controllers that need to perform the mapping logic.

      Why not just start with AutoMapper? Good question. It’s mainly a matter of YAGNI, and trying not to prematurely optimize. Until there is duplication, there’s little need for more then than the .Select approach. But yes, for any reasonably sized application that makes use of DTOs, AutoMapper usually is the approach that ends up making the most sense.

      I plan to write some more about this and to record my next WeeklyDevTips podcast on the subject as well. Checking out AutoMapper would certainly be worth your time and might remove a bunch of plumbing code from your DTOs/ViewModels.

      • Konrad

        this won’t work if you want to share your DTO with a client implemented in C# as well (to keep models synchronized all the time). In my opinion it’s best to put those things in extension methods or completely separate class.

        • ardalis

          You’re saying none of the 3 options I listed in the previous comment will work if you want to share your DTO with a client? How so? What kind of client – an over-the-wire one that will deserialize your DTO, or something else?

          • nightrush

            If the client is also made in C# and you want a shared assembly with DTOs then putting FromStore inside DTO class will require your client to reference your domain models as well. In my opinion mapping should be completely separated in such cases.

          • ardalis

            Yes, you’re correct. You would only use that approach in a small app that wasn’t sharing the DTOs cross-application. Otherwise, stick to AutoMapper or manually maping.

  • Rosen Petrov

    Using extension methods is also a way to implement the mappings. Just like ToList, ToDictionary, ToArray, etc. You could have an Extensions class per Model or group them by some logic. IMO it’s not a bad way at all because you still keep your Model classes clean, don’t have to think about injecting any other mapper classes to do the mapping, can keep together the mapping logic.

    • ardalis

      Indeed, this is another nice approach. Thanks for sharing it! Just take care that your extension methods never have dependencies on infrastructure that might make them hard to test. I’ve seen many clients who “extend” mapping to include fetching lookup values from a database, for instance, and this can quickly add a lot of unnecessary dependency to the application. But as long as you don’t do anything like that, this works well.

  • Paul Wheeler

    Absolutely!! We have all EF models and context as internal and only expose our Commands with each having it’s own Input/Output/Handler classes.

  • g____r

    Absolutely!

  • Aman Agrawal

    This is what I think as well, in one of the companies that I worked for I was trying to introduce DDD practices to the way we were building the product and I had a lot of back and forth with other devs who just couldn’t get the whole DTOs vs Domain object argument. In their minds there was nothing wrong with exposing the entities all the way out to the front, their argument was “we all know what we are doing, we can trust each other not to do the wrong thing or manipulate the domain object in a wrong way”. Putting a parameterised constructor and closing out the properties on the domain object for public modification, was shocking to them I guess they had been used to “direct property assignment” or transactional script style of development for way too long.

    DTOs especially are useful if your domain object is more complex than what you need out on the front or over the wire. DTOs will save on bandwidth costs and isolate accidental state mutations on the domain object. I can see why people turn up their noses at DTOs if your DTOs end up being the same structure as domain object i.e. you need to expose most of the state on the UI or over the wire and the domain objects are practically just data structures.

  • aaron

    I wouldn’t suggest a distinction between a public API, for outside applications/consumers, vs. an API for your Mobile or traditional web applications. In the case of the latter type you may want the flexibility of easily adding future fields to your object model. For these types of API’s I have created POCO model classes that are the base type for my Domain Objects.

  • Guillermo Zepeda

    Good article. Good practices worth applying.

  • Konrad

    Sometimes it is useful to create “mapper” constructors, also enums don’t need DTOs so they can be shared. I’d avoid mapper constructors if I wanted to share my models with the client implementation.

  • Havret

    Great article, Steve!

    I am wondering what do you think about applying these rules into CQRS/ES system. As I understand commands as DTOs shouldn’t carry any domain objects (i.e. value object), but what about events? Technically they are part of the domain, so it should be fine, but what in the scenario when I want to publish my events to notify my UI that something happened? I should map them to some sort of integration events which will contain only DTOs?