Routing in ASP.NET Web API (Routage dans l’API Web ASP.NET)

Cet article explique comment API Web ASP.NET achemine les requêtes HTTP vers les contrôleurs.

Notes

Si vous êtes familiarisé avec ASP.NET MVC, le routage d’API web est très similaire au routage MVC. La main différence est que l’API web utilise le verbe HTTP, et non le chemin d’URI, pour sélectionner l’action. Vous pouvez également utiliser le routage de style MVC dans l’API web. Cet article ne suppose aucune connaissance de ASP.NET MVC.

Tables de routage

Dans API Web ASP.NET, un contrôleur est une classe qui gère les requêtes HTTP. Les méthodes publiques du contrôleur sont appelées méthodes d’action ou simplement actions. Lorsque l’infrastructure d’API web reçoit une demande, elle achemine la demande vers une action.

Pour déterminer l’action à appeler, l’infrastructure utilise une table de routage. Le modèle de projet Visual Studio pour l’API web crée un itinéraire par défaut :

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Cet itinéraire est défini dans le fichier WebApiConfig.cs , qui est placé dans le répertoire App_Start :

Pour plus d’informations sur la WebApiConfig classe , consultez Configuration de API Web ASP.NET.

Si vous auto-hébergez l’API web, vous devez définir la table de routage directement sur l’objet HttpSelfHostConfiguration . Pour plus d’informations, consultez Auto-héberger une API web.

Chaque entrée de la table de routage contient un modèle d’itinéraire. Le modèle d’itinéraire par défaut pour l’API web est « api/{controller}/{id} ». Dans ce modèle, « api » est un segment de chemin littéral, et {controller} et {id} sont des variables d’espace réservé.

Lorsque l’infrastructure d’API web reçoit une requête HTTP, elle tente de faire correspondre l’URI à l’un des modèles d’itinéraire dans la table de routage. Si aucune route ne correspond, le client reçoit une erreur 404. Par exemple, les URI suivants correspondent à l’itinéraire par défaut :

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

Toutefois, l’URI suivant ne correspond pas, car il manque le segment « api » :

• /contacts/1

Notes

La raison d’utiliser « api » dans l’itinéraire est d’éviter les collisions avec ASP.NET routage MVC. De cette façon, « /contacts » peut accéder à un contrôleur MVC et « /api/contacts » à un contrôleur d’API web. Bien sûr, si vous n’aimez pas cette convention, vous pouvez modifier la table de routage par défaut.

Une fois qu’un itinéraire correspondant est trouvé, l’API web sélectionne le contrôleur et l’action :

• Pour rechercher le contrôleur, l’API web ajoute « Controller » à la valeur de la variable {controller} .
• Pour trouver l’action, l’API web examine le verbe HTTP, puis recherche une action dont le nom commence par ce nom de verbe HTTP. Par exemple, avec une requête GET, l’API web recherche une action précédée de « Get », telle que « GetContact » ou « GetAllContacts ». Cette convention s’applique uniquement aux verbes GET, POST, PUT, DELETE, HEAD, OPTIONS et PATCH. Vous pouvez activer d’autres verbes HTTP à l’aide d’attributs sur votre contrôleur. Nous en verrons un exemple plus tard.
• D’autres variables d’espace réservé dans le modèle d’itinéraire, telles que {id}, sont mappées aux paramètres d’action.

Intéressons-nous à un exemple. Supposons que vous définissez le contrôleur suivant :

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

Voici quelques requêtes HTTP possibles, ainsi que l’action appelée pour chacune d’elles :

Verbe HTTP	Chemin de l’URI	Action	Paramètre
GET	api/products	GetAllProducts	(none)
GET	api/products/4	GetProductById	4
Suppression	api/products/4	DeleteProduct	4
POST	api/products	(aucune correspondance)

Notez que le segment {id} de l’URI, le cas échéant, est mappé au paramètre id de l’action. Dans cet exemple, le contrôleur définit deux méthodes GET, l’une avec un paramètre id et l’autre sans paramètre.

Notez également que la requête POST échoue, car le contrôleur ne définit pas de méthode « Post... ».

Variantes de routage

La section précédente décrit le mécanisme de routage de base pour API Web ASP.NET. Cette section décrit certaines variantes.

Verbes HTTP

Au lieu d’utiliser la convention d’affectation de noms pour les verbes HTTP, vous pouvez spécifier explicitement le verbe HTTP pour une action en décorant la méthode d’action avec l’un des attributs suivants :

• [HttpGet]
• [HttpPut]
• [HttpPost]
• [HttpDelete]
• [HttpHead]
• [HttpOptions]
• [HttpPatch]

Dans l’exemple suivant, la FindProduct méthode est mappée aux requêtes GET :

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

Pour autoriser plusieurs verbes HTTP pour une action, ou pour autoriser des verbes HTTP autres que GET, PUT, POST, DELETE, HEAD, OPTIONS et PATCH, utilisez l’attribut [AcceptVerbs] , qui prend une liste de verbes HTTP.

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

Routage par nom d’action

Avec le modèle de routage par défaut, l’API web utilise le verbe HTTP pour sélectionner l’action. Toutefois, vous pouvez également créer un itinéraire où le nom de l’action est inclus dans l’URI :

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Dans ce modèle d’itinéraire, le paramètre {action} nomme la méthode d’action sur le contrôleur. Avec ce style de routage, utilisez des attributs pour spécifier les verbes HTTP autorisés. Par exemple, supposons que votre contrôleur dispose de la méthode suivante :

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

Dans ce cas, une requête GET pour « api/products/details/1 » correspond à la Details méthode . Ce style de routage est similaire à ASP.NET MVC et peut convenir à une API de style RPC.

Vous pouvez remplacer le nom de l’action à l’aide de l’attribut [ActionName] . Dans l’exemple suivant, deux actions sont mappées à « api/products/thumbnail/id. L’un prend en charge GET et l’autre prend en charge POST :

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

Non-actions

Pour empêcher l’appel d’une méthode en tant qu’action, utilisez l’attribut [NonAction] . Cela signale au framework que la méthode n’est pas une action, même si elle correspond aux règles de routage.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

En savoir plus

Cette rubrique a fourni une vue d’ensemble du routage. Pour plus d’informations, consultez Routage et sélection d’action, qui décrit exactement comment l’infrastructure fait correspondre un URI à un itinéraire, sélectionne un contrôleur, puis sélectionne l’action à appeler.