Enumeration class as query string parameter

Posted by

This is my third post in the Series: Enumeration classes – DDD and beyond. If you are new to the Enumeration class, I suggest going through my previous posts.

Source Code

You can find the source code of this series at this GitHub link.

Using Enum as a query string parameter

In an HTTP Get request, we can pass additional parameters in the query string. These parameters are typically a string or an integer data type. 

Since an Enum is a Value-Type, we can parse Enum into a string or an integer. That helps us to use the Enum in a query string parameter without any drama.

For example, consider below Enum, PaymentType:

Using an Enum as a query string parameter is easy; it does not require any special setup.

The below API endpoint demonstrates how we can use PaymentType Enum as a query string parameter to return the PaymentType code.

The client can call the API endpoint with either an integer or string enum value.

Figure 1: Query string can parse Enum value as both integer and string
Figure 2: Bad request when Enum value is not valid

Enumeration class as a query string parameter

Unlike an Enum type, the Enumeration class is not a value-type. We would need custom logic to bind it as a query string parameter.

The good news is that we can achieve this without massive effort through custom Model Binders.

From Microsoft documentation:

Model binding uses specific definitions for the types it operates on. A simple type is converted from a single string in the input. A complex type is converted from multiple input values. The framework determines the difference based on the existence of a TypeConverter. We recommended you create a type converter if you have a simple string -> SomeType mapping that doesn’t require external resources.

We can create a custom Model Binder for the Enumeration class as below:

As you can see in the above code, we get the value of the incoming field and then validate it against passed Enumeration class type. If the incoming value matches against Enumeration Value or Name, then bind the result and return Success. Else, add a Model error and return Failed.

To use this ModelBinder, we need to implement an IModelBinderProvider. In IModelBinderProvider implementation, we would need to create an instance of generic EnumerationQueryStringModelBinder with the type of Enumeration inferred at the runtime. To create an instance of a generic 

First, we create a static class, EnumerationQueryStringModelBinder, with a static method to create an instance of EnumerationQueryStringModelBinder<T>.

Next, we create an EnumerationQueryStringModelBinderProvider, which implements the GetBinder method of interface IModelBinder.

Last but not least, we register our IModelBinderProvider in Startup.cs.


Let us go back to our Payment Type Enumeration class from previous posts.

We can convert the original API endpoint to use the PaymentType Enumeration class as a query string request parameter.

Our API endpoint works the same way as before.

Figure 3: Enumeration class binded as Query string

It also returns a Bad Request (404) when the client passes an invalid Enumeration name or value.

Figure 4: Bad request when Model binder cannot parse the Enumeration class

Wrapping up

In this post, I explained how you could use an Enumeration class as a query string parameter. With JSON Serialization and Model Binding, I have tried to cover the most common uses-cases of using Enumeration class as an alternate to Enum. I hope you find these posts helpful.