I have come across quite a few ASP.NET Core WebAPI solutions where there is a inordinate number of Data Transfer Object (DTO) classes. This results in a kind of class explosion which I think can be avoided. Yes, DTOs do have their utility, no doubt. But, many a times as the application evolves and grows, we often end up with numerous DTOs and these DTOs sometimes differ just by a handful of attributes or in some cases they are a simple composition of multiple entities / DTOs.

One of the reasons we have so many such DTO classes is the need to pass data to and from repository and service layer ( between different layers of the application for that matter). In order to find a way around creating yet another DTO, I was exploring some options and realized that Tuples can be used to minimize the creation of DTOs

Tuples have been around in C# for quite sometime now. I am not sure if it is a common knowledge but I recently figured out that you could eliminate quite a few DTOs that we use to ferry data between the layers by leveraging Tuples

Let us take the following scenario of instance.

We have an API, say, GetCustomers which, of course, will return me the list of customers . And, we have an entity, Customer as defined below.

class Customer
{
public int customerId {get; set;}
public string firstname {get; set;}
public string lastname {get; set;}
}

The API response for our GetCustomers API is as below

You would have noticed that the attribute count is expected in the response and this is not present in our Customer class. The repository layer would just return a List but the service layer needs to pass it along with the count attribute to the controller. This is usually where we tend to create a DTO as below.

class CustomerDTO
{
int count;
List customers
}

The only reason for the above class to exist is to ferry the data from repository in a format that the controller is expecting. We can eliminate this class altogether by returning Tuple as below

return new Tuple<int, List>(result.Count,result)

Granted, this is a very trivial scenario and you can add the count attribute in the controller and return an anonymous type also.

Now consider the cases when you need a response that is aggregation of multiple custom types. For instance, if we have two API one to get customer and another to get order details we would have created two DTO for Customer and Order. If a new API is required that gives details pertaining to a particular Customer and all related Orders as response, you might have to create a new DTO again, as below.

public class newDTO {
public int orderCount {get; set;}
public int customerId {get; set;}
public List orders {get; set;}
}

The expected response is

This is exactly what we can avoid by using Tuples like below in the service and repository layer.

RepositoryLayer.cs

var repoResponse = new Tuple<int, Customer customer, List>(count,custResult, orderResult);
return repoResponse;

custResult holds a particular customer’s data and orderResult will be a List

ServiceLayer.cs

.
.
.
//Create a Tuple with three members, count, customer and orders
//repoResponse is the response from your repository(a Tuple)
(int count, Customer customer, List orderList) result = (repoResponse.Item1, repoResponse.Item2, repoResponse.Item3);

return result;
}

From the above service response, the controller can create an anonymous type as below without ever creating a DTO and return the response .

return new { ordercount= serviceResponse.count, customer = serviceResponse.customer.customerId, serviceResponse = serviceResponse.orderList };

It should be noted that, although this approach eliminates the need to create DTO classes, it come at the cost of readability. Your method signatures may not be very elegant and readable. While DTOs will still be the right way to go in some scenarios, for others, Tuples can help.

Hope this helps in reducing a few DTOs at your end.

Cheers!

I have written my fair share of RESTful API but am no expert by any measure. I had never given enough thought about the HTTP Verbs I should be using (like, PUT, POST, PATCH) while writing API. If a resource had to be created, I would automatically go for POST (_never considered the idempoten_cy angle at all) and if a resource had to be modified, I would go for PATCH.

On one of my API assignments, I decided to make a very conscious and deliberated choice of the verbs I will be using; and an API in particular got me thinking.

I had to write an API to modify a resource and this resource happened to have nested resources and numerous attributes. I soon realized that it wasn’t so straight forward to create an elegant PATCH API due to the sheer number of attributes on this resource that can potentially get modified (Why did you design a resource with so many attributes in the first place? you might ask. But that is a topic for another day)

So, coming back to the task in hand, I was aware of only two choices to go about writing a PATCH call. Either, send just the attributes requiring modifications to the API (Approach 1) or end the entire resource to API after making changes to the necessary attributes at consumers’ end (Approach 2). We will examine both the approaches in the context of the below two classes (Employee and Address)

    public class Employee  
    {  
        public int EmployeeId {get; set;}  
        public string EmployeeName {get; set;}  
        public Address EmployeeAddress {get; set;}  
        public string WorkLocation {get; set;}  
        public List<string> PreferredWorkLocations {get; set;}

    }

    public class EmployeeAddress  
    {  
        public string HouseNumber {get; set;}  
        public string AddressLine1 {get; set;}  
        public string AddressLine2 {get; set;}  
    }

Approach 1: The consumer of the PATCH API will send the entire resource, after changing a few select attribute that need to be modified. At the API end, the PATCH payload will be handed over to the repository layer which would then update the entire resource to the database. Other than some basic validations, no additional work is needed at the API end. A sample PATCH call (almost a PUT) would look like below

    **api/ModifyEmployee/{empId}  
    **{  
    "EmployeeName" : "ename",  
    "EmployeeAddress" : {  
                "HouseNumber" : "F32",  
                "AddressLine1" : "Addr1",  
                "AddressLine2" : "Addr2"  
                },  
    "WorkLocation" : "Brazil",  
    "PreferredWorkLocations" : \["Brazil","France"\]  
    }

Downside: the consumer has to build the entire object even if only a single attribute requires modification. Also note that, there is no way of knowing if just the “houseNumber” has changed or any other / all the attributes of Employee has changed. So, all the attributes’ values need to be copied back to a new object object to be persisted in the database.

Approach 2: The consumer of the API will send only the attribute that had to be modified. A sample PATCH for modifying the work location will look like below:

    **api/ModifyEmployeeWorkLocation/{empId}  
    **{  
    "WorkLocation" : "Brazil"  
    }

Downside: the onus of constructing an object that can be handed over to the repository layer falls on the API service layer (an object mapper need to be used here)

Further, this approach might necessitates that a new API be created of each combination of possible modifications in the resource attributes. Consider if I have to update the Employee Address I will have to have another method like api/ModifyEmployeeAddress/{empId}. If the class has many attributes that could be modified this can lead to explosion of PATCH methods.

JSON Patch

Neither of the approaches appealed to me. This is when I stumbled upon JSON PATCH. Honestly, I had never heard of JSON Patch before and wanted to give it a shot as I thought it would address the downsides mentioned above.

What I like the most about JSON Patch was that as a consumer I don’t have to send the entire object as payload for the PATCH call, I can just mention what operation (add / remove / replace / copy) I want to perform on which resource attribute / subset of attributes. Also, at the API end, I there is not need to have multiple methods for each type of modifications and there is no need to manually copy over the incoming values to a new object that the repository will understand and persist

Using JSON Patch, these call can be as simple as below

    **\[    
        {**  
            "**value**": "address line one",  
            "**path**": "/address/addressLine1",  
            "**op**": "replace"  
        **}  
    \]**

The advantage of using JSON Patch is that you don’t have to reconstruct the object at your API end. You can use a middle-ware like NewtonsoftJsonPatch and simply use ApplyTo method to construct the object for persistence / further processing.

    public async Task<IActionResult> UpdateEmployee(\[FromBody\] **JsonPatchDocument<Employee>** patchDoc, int empId)  
    {  
        if (patchDoc != null)  
        {  
            var emp = await <yourCache>.GetAsync<Employee>("cacheKey");

            if (emp == null)   
            {  
                emp = await yourService.GetEmployeeData(empId);  
            }

            **patchDoc.ApplyTo(emp, ModelState);**

            //call repository to update.   
            \_ = await yourService.UpdateAsync(emp);

            return new ObjectResult(emp);  
        }  
        else  
        {  
            return BadRequest(ModelState);  
        }  
    }

The ApplyTo method will take care of copying (or performing any operation based on the value supplied in “op” attribute of the PATCH call) the new values to the existing object. This eliminates the need to do this mapping and copying manually using a mapper.

Another plus is that you don’t have to have multiple PATCH calls for each of the attributes, you can club multiple modification requests in the same PATCH call like below. Please note that you have to use /- notation to add to a list.

    \[  
    {  
            "value": "new work Location",  
            "path": "/preferredWorkLocations/-",  
            "op": "add"  
    },  
    {  
            "value": "address line one",  
            "path": "/address/addressLine1",  
            "op": "replace"  
    }  
    \]

You may refer to the below link for detailed information on how to use JSON Patch in ASP.NET Core.

JsonPatch in ASP.NET Core web API
_By Tom Dykstra and Kirk Larkin This article explains how to handle JSON Patch requests in an ASP.NET Core web API. To…_docs.microsoft.com

So, that’s how I embraced JSON Patch.

Cheers!