web-dev-qa-db-ja.com

Web APIで列挙型パラメーターを渡すためのベストプラクティス

RESTful Web APIプロジェクトがあり、ベストプラクティスがわからない2つの異なるEnumシナリオがあります。

シナリオ1:単純な列挙型パラメーター

APIメソッドには、ruleTypeというパラメーターが必要です。有効な値はEmailAddressおよびIPAddressです。 Web APIプロジェクト内の私の列挙型は次のようになります。

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

このシナリオに関する私の質問は、?ruleType=EmailAddress AP​​Iへのリクエストで(APIメソッド内のRuleTypeプロパティにその値を自動的にバインドします)?そうである場合、RuleType paramが送信されたことを有効に検証するには、有効なRuleType列挙値が必要ですか?

シナリオ2:単一のパラメーターの複数の列挙値

私のAPIメソッドにはオプションのfields paramがあり、これにより、返される追加データを指定できます。例えば。 &fields=ruleOwner,rule。これにより、応答でこれらの2つの追加ビットのデータが返されます。

要求される可能性のある各fieldに関連するWeb APIプロジェクトに列挙があり、現在、コンマで区切られたフィールドparamを分割し、その列挙の各文字列表現をループして、それを解析しています同等の列挙型に変換すると、列挙型の値のリストが生成され、API内で使用して関連データを取得できます。

これが列挙です:

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

ここでのベストプラクティスは何ですか?私はビット単位の列挙型を探していたので、単一の値がAPIリクエストで送信され、fieldsの任意の組み合わせになりましたが、これがWeb APIでうまく機能するかどうか、一般的には良いかどうかはわかりませんでしたこれについて行く方法?

20
marcusstarnes

uRIを「人間が読める」ようにすることがベストプラクティスです。ですから、Enumを文字列として使用する理由も理解できます。しかし、HristoKolevが述べたように、カスタムモデルバインダーを作成する必要があります。

フィールドでは、列挙型の組み合わせを使用しないでください。理解するのが難しいからですおそらく、列挙型エントリとして列挙型の組み合わせを作成できます

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

最も単純な答えは、「問題ではない」です。

コントローラーメソッドのパラメーターが列挙型の場合

public IHttpActionResult Foo(RuleType ruleType)

WebAPIでは、It Just Works-クライアント要求URLでパラメーター値が?ruleType=1 または ?ruleType=EmailAddress

クライアントが列挙に無効な値を指定すると、例外がスローされます(The parameters dictionary contains a null entry for parameter 'ruleType' of non-nullable type 'RuleType' for method 'Foo' ...およびクライアントは400 Bad Request応答。

20
Mr. T

シナリオ2では、[フラグ]属性を使用した列挙型のビットマスク操作のC#のサポートが組み込まれています

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

this SO post で説明されています

Christian の回答ですでに述べたように、これをREST APIで使用することはおそらく良い方法ではありませんが、動作するはずです。

4
Chris W

複数の値であってもなくても、Enumを文字列として使用している場合は、手動で解析する必要があります。 .NETでは、Enumは整数であるため、デフォルトのモデルバインダーに列挙を送信する場合は、次のようにする必要があります。?ruleType=1

文字列を受け入れる独自のモデルバインダーを作成できますが、なぜそれを行うのかを自問する必要がありますか?ユーザーがURLを簡単に識別できるようにする場合は、文字列を使用します。そうでない場合、整数を使用しない理由はありません。前述のように、FlagsAttributeを使用して複数の値を組み合わせることができます。

0
Hristo Kolev