In precedenti articoli abbiamo visto come ASP.NET Web API ci consenta di realizzare una API RESTful, incentrata sul concetto di risorsa e particolarmente indicata per lo sviluppo di applicazioni data-driven.

A volte, però, abbiamo la necessità di arricchire il nostro servizio HTTP con altre operazioni, oltre alle consuete Get, Post, Put e Delete. Proviamo dunque ad aggiungere una action personalizzata in un ApiController già esistente.

public class ClientiController : ApiController
{
  [HttpGet]
  public IEnumerable<Cliente> TopTen() { /* omissis */ }
}

Come sappiamo, ASP.NET Web API individua la action da eseguire in base al verbo HTTP utilizzato per la richiesta; per questa ragione, questa nuova action non verrà esposta nella Web API e pertanto non potrà essere consumata dai client. Ne troviamo conferma visitando la pagina /Help, che infatti non menziona la nostra Action nella documentazione. Se anche provassimo ad inviare una richiesta a /api/Clienti/TopTen, otterremmo un errore.

Il problema è legato alla HttpRoute di default, che non ci lascia selezionare la Action dall'URL, dato che nel routeTemplate non è presente il frammento {action}.

config.Routes.MapHttpRoute(
  name: "DefaultApi",
  routeTemplate: "api/{controller}/{id}",
  defaults: new { id=RouteParameter.Optional }
);

La soluzione più immediata consiste nell'aprire il file /App_Start/WebApiConfig.cs e reintrodurre il frammento {action}.

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

Ora riusciremo a consumare l'Action personalizzata con una richiesta GET all'indirizzo /api/Clienti/TopTen. Bisogna tenere presente che, così facendo, avremo rinunciato al meccanismo di selezione originale. D'ora in poi, anche i nomi delle Action Get, Post, Put e Delete dovranno apparire nell'URL. Per esempio, una richiesta GET dovrà essere inviata all'indirizzo /api/Clienti/Get/1.

Si tratta di una soluzione certamente percorribile ma non consigliata per applicazioni che sono già in produzione, dato che la modifica al routeTemplate rappresenta una breaking change. In secondo luogo, viola un po' la natura RESTful del servizio HTTP, dato che ora non disponiamo più di uno stesso indirizzo base per tutte le operazioni CRUD che interessano la risorsa.

Nel prossimo script capiremo come risolvere questa limitazione.