Het succes van een softwareproduct wordt tegenwoordig mede bepaald door extensibiliteit en integreerbaarheid in een web-omgeving. Wie snel wil groeien opent zijn deuren voor derden. Met de Web API-bibliotheek van Microsoft kan je in een handomdraai een RESTful-service opzetten. In deze korte instructie nemen we de nodige stappen door.
Introductie
De WCF Web API is een softwarebibliotheek geïntroduceerd door het WCF-team van Microsoft. De bibliotheek stelt ontwikkelaars in staat een RESTful-service te implementeren op basis van bestaande DTO’s en Service-klassen. Middels het decoreren van methodes met attributen stellen we deze beschikbaar in een service. De bibliotheek ondersteunt verscheidene overdrachtsformaten zoals XML, JSON en OData.
Naast het vergroten van de extensibiliteit en integreerbaarheid biedt het ook andere mogelijkheden. Denk bijvoorbeeld aan een backendcommunicatiemechanisme voor rich-clients, zoals jQuery, Knockout JS of andere frameworks.
Stap 1: download de benodigdheden
Alvorens we aan de slag kunnen dienen we eerst de Web API-bibliotheek en andere vereisten te verkrijgen. Dit kan op twee manieren; als zijnde zip-bestand via de website (http://wcf.codeplex.com/releases) of via een NuGet-pakket via Visual Studio. Dit laatste zorgt dat alle benodigdheden automatisch in het project gezet en geconfigureerd worden.
Stap 2: decoreer je code
Aan de Business Entities of Data-Transfer-Objects (DTO) hoeven we waarschijnlijk weinig te doen. De properties of fields moeten publiekelijk gezet kunnen worden en er dient een default (parameterloze) constructor te zijn (zoals in listing 1).
public class Activity {
public Activity() { } public int Id { get; set; } public string Name { get; set; } public bool AllowBooking { get; set; }}
Listing 1: voorbeeld Data-Transfer-Object
Aan de service-klasse dient wel het één-en-ander te worden toegevoegd. Allereest moeten we de klasse decoreren met het ServiceContract-attribuut. Vervolgens moeten we het WebInvoke-attribute introduceren aan de CRUD-methodes (zie listing 2). We dienen daarbij een aantal zaken op te geven, die er uiteindelijk voor zorgen dat elk binnenkomend http-verzoek gekoppeld wordt aan de juiste methode. We geven hier de http-methode op, bijvoorbeeld GET, POST, PUT of DELETE, en eventueel een patroon waaraan de url moet voldoen (zoals bij de GetById-methode).
[ServiceContract]
public class ActivityService
{
private readonly ICollection<Activity> activities; [WebInvoke(UriTemplate = "", Method="GET")] public IQueryable<Activity> Get() { return activities.AsQueryable(); }
[WebInvoke(UriTemplate = "/{id}", Method = "GET")] public Activity GetById(int id) { return activities.FirstOrDefault(a => a.Id == id); }
[WebInvoke(UriTemplate = "", Method = "POST")] public HttpResponseMessage Save(Activity activity) { activities.Add(activity); return new HttpResponseMessage(HttpStatusCode.Created); }
}
Listing 2: een gedecoreerde service-klasse
De Web API-bibliotheek verzorgt de brug tussen http-verzoek en methode-aanroep en de vertaling tussen de overdracht- en opslagformaten. Wanneer we de resultaatwaarde tevens van type het IQueryable maken wordt dit automatisch een OData-databron.
Stap 3: introduceer een endpoint voor de service
Als laatste stap moeten we aangeven naar welk adres de service moet luisteren, bijvoorbeeld http://localhost/api/activities. De koppeling (route) tussen het http-endpoint en de service-klasse maken we kenbaar op vergelijkbare wijze als in .NET MVC. In de applicatie-opstartmethode (bijvoorbeeld global.asax/Application_Start
) introduceren we de route aan RouteTable (zie listing 3).
private void InitializeRoutes()
{
var routes = RouteTable.Routes; var hostFactory = new HttpServiceHostFactory();
routes.Add(new ServiceRoute( "api/activities", hostFactory, typeof(ActivityService) ));
}
Listing 3: het initialiseren van de routes
Testbaarheid en resultaat
De bibliotheek komt met een ingebouwde test-interface, die ingeschakeld kan worden tijdens de opstartfase van de applicatie. De interface wordt getoond wanneer we /test toevoegen aan het adres van een http-endpoint (url).
Figuur 1: test-interface
In dit artikel hebben we gelezen hoe we in drie eenvoudige stappen een applicatie kunnen verrijken met functionaliteit om deze open te stellen aan het web. De Web API-bibliotheek verbergt de achterliggende boilerplate-code en vereist een enkele aanpassing om operationeel te zijn.
Voetnoot
Op de website van de Web API is te lezen dat de bibliotheek momenteel alleen nog maar gebruikt mag worden in eigen beheerde omgevingen. De bibliotheek mag niet gedistribueerd worden als een onderdeel naar derden.