Best practice for passing enum params in Web API

Question

I have a RESTful Web API project, and I have 2 different Enum scenarios that I'm unsure of re best practice.

Scenario 1 : Straightforward Enum Param

My API method requires a parameter called ruleType, with valid values being EmailAddress and IPAddress. My enum within the Web API project looks like this:

public enum RuleType
{
    None = 0,
    EmailAddress = 1,
    IPAddress = 2
}

My question for this scenario is, should I use ?ruleType=EmailAddress in my request to the API (which automatically binds that value to my RuleType property within the API method)? If so, how best to validate that the RuleType param sent, is a valid RuleType Enum value?

Scenario 2 : Multiple Enum Values for a Single Param

My API method has an optional fields param, which is allows you to specify any additional data that should be returned. E.g. &fields=ruleOwner,rule. This would return those 2 extra bits of data in the response.

I have an enum in the Web API project which relates to each possible field that may be requested, and at present, I am splitting the comma separated fields param, then looping through each string representation of that enum, parsing it to the equivalent enum, resulting in a list of Enum values which I can then use within my API to retrieve the relevant data.

This is the Enum:

public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    etc.
}

What would be best practice here? I was looking into bitwise enums, so a single value is sent in the API request which resulted in any combination of fields but didn't know if this would work well with a Web API, or if there's generally a better way to go about this?

Answer 1

The simplest answer is, "It doesn't matter".

If the parameter in your controller method is of the enumeration type

public IHttpActionResult Foo(RuleType ruleType)

In WebAPI, It Just Works - no matter if the client request URL specifies the parmeter value as ?ruleType=1 or ?ruleType=EmailAddress

If the client specifies a value that isn't valid for the enumeration, an exception is thrown (The parameters dictionary contains a null entry for parameter 'ruleType' of non-nullable type 'RuleType' for method 'Foo' ... and the client gets a 400 Bad Request response.

Answer 2

it is a best practice to make the URI "human readable". so i can also understand why you using Enum as a string. But as HristoKolev said you have to write a custom Model Binder.

In fields i think you should not use an combination of enums. because it is difficult to understand. perhaps you can create an combination of enum as enum entry

public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    RuleAndRuleOwner = 3,
    etc.
}

Answer 3

For scenario 2 there is built in support in C# for Bitmask operations in Enums using the [Flags] attribute

[Flags]
public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    RuleAdministrator = 4,
    RuleEditor = 8,
    ...etc
}

Which is described in this SO post

As Christian already stated in his answer it's probably not good practice to use this in a REST API but it should work.

Answer 4

Multiple values or not, if you are using an Enum as a string, you have to parse it manually. In .NET the Enums are integers so if you want to send an enum to the default model binder you have to do it like this: ?ruleType=1.

You can write your own model binder that will accept string, but you have to ask yourself why are we doing it? If you want the user to be able to easily identify the url then use strings. If not there is no reason not to use integers. As you said, you can use FlagsAttribute to combine multiple values.

Answer 5

In .Net Core you can add below statement in ConfigureServices() method in StartUp.cs or Program.cs bepending on what version of .NET Core you are using.

services.AddControllers()
    .AddJsonOptions(opt=> { opt.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()); });