web-dev-qa-db-fra.com

Méthode recommandée pour passer des paramètres d'énumération dans l'API Web

J'ai un projet d'API Web RESTful et deux scénarios Enum différents pour lesquels je ne suis pas sûr de la meilleure pratique.

Scénario 1: Simple Enum Param

Ma méthode d'API nécessite un paramètre appelé ruleType, les valeurs valides étant EmailAddress et IPAddress. Mon énumération dans le projet d'API Web ressemble à ceci:

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

Ma question pour ce scénario est la suivante: dois-je utiliser ?ruleType=EmailAddress dans ma demande à l'API (qui lie automatiquement cette valeur à ma propriété RuleType dans la méthode de l'API)? Si tel est le cas, quelle est la meilleure méthode pour valider l'envoi du paramètre RuleType, est-il une valeur RuleType Enum valide?

Scénario 2: Valeurs Enum multiples pour un paramètre unique

Ma méthode API a un paramètre fields facultatif, qui vous permet de spécifier les données supplémentaires à renvoyer. Par exemple. &fields=ruleOwner,rule. Cela renverrait ces 2 bits de données supplémentaires dans la réponse.

J'ai un enum dans le projet Web API qui concerne chaque field possible qui peut être demandée, et à l'heure actuelle, je divise les champs param par des virgules, puis en parcourant chaque représentation sous forme de chaîne de cet enum, en l'analysant en un enum équivalent, Il en résulte une liste de valeurs Enum que je peux ensuite utiliser dans mon API pour récupérer les données pertinentes.

C'est l'énumération:

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

Quelle serait la meilleure pratique ici? J'examinais les bits au niveau des bits, de sorte qu'une seule valeur est envoyée dans la demande d'API, ce qui entraîne une combinaison de fields mais ne sait pas si cela fonctionnerait bien avec une API Web ou s'il existe généralement une meilleure façon de procéder. ?

c#restasp.net-web-apienums
13
marcusstarnes

il est recommandé de rendre l'URI "lisible par l'homme". Je peux donc aussi comprendre pourquoi vous utilisez Enum en tant que chaîne. Mais comme HristoKolev l'a dit, vous devez écrire un classeur de modèle personnalisé. 

Dans les domaines, je pense que vous ne devriez pas utiliser une combinaison d’énums. parce que c'est difficile à comprendre. peut-être pouvez-vous créer une combinaison d'enum comme entrée enum 

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

La réponse la plus simple est "peu importe". 

Si le paramètre dans votre méthode de contrôleur est du type énumération

public IHttpActionResult Foo(RuleType ruleType)

Dans WebAPI, Cela fonctionne simplement - peu importe si l'URL de la demande du client spécifie la valeur du paramètre telle que ?ruleType=1 ou ?ruleType=EmailAddress

Si le client spécifie une valeur non valide pour l'énumération, une exception est levée (The parameters dictionary contains a null entry for parameter 'ruleType' of non-nullable type 'RuleType' for method 'Foo' ... et le client obtient une réponse 400 Bad Request.

8
Mr. T

Pour le scénario 2, la prise en charge intégrée dans C # des opérations de masque de masque dans Enums utilise l'attribut [Flags]. 

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

Ce qui est décrit dans ce SO post

Comme Christian l'a déjà indiqué dans sa réponse, ce n'est probablement pas une bonne pratique de l'utiliser dans une API REST mais cela devrait fonctionner.

2
Chris W

Valeurs multiples ou non, si vous utilisez un Enum en tant que chaîne, vous devez l'analyser manuellement. Dans .NET, les énumérations sont des entiers. Par conséquent, si vous souhaitez envoyer une énumération au classeur de modèle par défaut, procédez comme suit: ?ruleType=1.

Vous pouvez écrire votre propre classeur de modèle qui accepte les chaînes, mais vous devez vous demander pourquoi nous le faisons. Si vous voulez que l'utilisateur puisse facilement identifier l'URL, utilisez des chaînes. Sinon, il n'y a aucune raison de ne pas utiliser de nombres entiers. Comme vous l'avez dit, vous pouvez utiliser FlagsAttribute pour combiner plusieurs valeurs.

0
Hristo Kolev