Building Web Services with Windows Azure (new): Quickly develop scalable, REST-based applications or services and learn how to manage them using Microsoft Azure

ASP.NET Web API provides an easy and extensible mechanism to expose data and functionality to a broad range of clients, including browsers and modern web and mobile apps. The most significant aspect of ASP.NET Web API is that it is targeted to enable support for HTTP and RESTful services. In this section, we will discuss the nuts and bolts of the Web API framework.

Before we delve into the building blocks and design principles behind ASP.NET Web API, it is important to understand that ASP.NET Web API is an evolution of the existing continuous Microsoft efforts to enable support for HTTP Services. A timeline of events that describe this evolution are outlined next.

Windows Communication Foundation (WCF) (https://msdn.microsoft.com/en-us/library/ms731082%28v=vs.110%29.aspx) was launched with .NET 3.0 for SOAP-based services; the primary aim was to abstract the transport layer and enable support for the WS-* protocol. No HTTP features were enabled except HTTP POST for requests

In NET 3.5, WebHttpBinding (https://msdn.microsoft.com/en-us/library/system.servicemodel.webhttpbinding%28v=vs.110%29.aspx) was introduced in WCF with the intent to support services that were not based on SOAP. It allowed systems to configure endpoints for WCF services that are exposed through HTTP requests instead of SOAP messages. The implementation was very basic and most HTTP protocol features were still missing or needed to be coded separately.

WCF Starter Kit (https://aspnet.codeplex.com/releases/view/24644) preview was launched to provide a suite of helper classes, extension methods, and Visual Studio project templates for building and consuming HTTP REST-based services. A new WebServiceHost2 type was added to host RESTful services. Also, client HTTP support was added to provide a more natural experience for HTTP programming. The project never got released and eventually migrated into WCF Web API. As of August 2009 the project is in preview status.

During the same time, ASP.NET released some basic support to create REST APIs with its .NET 4.0 release. Its capabilities were limited, and HTTP features such as content negotiation were not available. ASP.NET was still targeted towards building web applications.

WCF Web API (http://wcf.codeplex.com/wikipage?title=WCF%20HTTP) was technically the first attempt to create a framework to support HTTP services from the ground up. However, the development efforts still leveraged pieces from WCF REST Starter Kit and .NET 3.5. A new rich, high-level HTTP programming model was adopted that included full support for content negotiation. A variety of traditional formats were supported (XML, JSON, and OData), and server-side query composition, ETags, hypermedia, and much more was enabled. The development was simplified by introducing the use of HttpRequestMessage and HttpResponseMessage to access requests and responses. The WCF Web API's second release was compatible with ASP.NET and allowed registering routes for Web APIs similar to ASP.NET MVC.

The WCF Web API project merged with the ASP.NET team to create an integrated Web API framework, and ASP.NET Web API was born. It shipped with the MVC4 Beta release in February 2012 and went to RTM in August 2012.

ASP.NET Web API 2 was released in October 2013 with new features such as attribute routing and authorization with OAuth 2.0. Another version, 2.1, was released in January 2014 with improvements to the existing infrastructure and additional features such as global exception handling.

At the time of writing, ASP.NET Web API 2.2 is the current stable version of the ASP.NET Web API framework. It includes more improvements to existing features such as enabling client support for Windows 8.1 devices along with bug fixes.

As described in the previous section, ASP.NET Web API is built on top of existing frameworks and technologies. Web API leverages features from ASP.NET MVC, the core ASP.NET framework, and the .NET framework to reduce the overall learning curve for developers and at the same time provides abstraction to make programming easier. The following figure highlights the key features that make up the ASP.NET Web API framework.

Now that we understand the intent behind ASP.NET Web API, let's discuss some design principles on which ASP.NET Web API is based:

In the preceding example:

As mentioned before, ASP.NET Web API enables customers to easily and rapidly develop HTTP-based services that can result in new business opportunities or improved customer satisfaction. Some of these scenarios are described here:

Let's talk about some of the internal workings of ASP.NET Web API and how a request is received and a corresponding response generated.

Anatomy of the API of ASP.NET Web API

Before we understand the request and response lifecycle within ASP.NET Web API, it is important to comprehend some of the principal types and their usage within the pipeline.

The core assemblies for ASP.NET Web API can be installed using the Microsoft.AspNet.WebApi NuGet package, which is distributed under the MS license, this will install all the required dependencies to develop an ASP.NET Web API service.

Note

NuGet is the package manager for the Microsoft development platform, including .NET. The NuGet client tools provide the ability to produce and consume packages. NuGet is installed as part of the Visual Studio 2013 release. To know more about NuGet, visit https://www.nuget.org/.

To install the runtime packages via the NuGet Package Manager Console in Visual Studio use the following command:

PM> Install-Package Microsoft.AspNet.WebApi

Alternatively, Visual Studio provides a NuGet user interface dialog that can be used to install the package. For more information on using the NuGet dialog in Visual Studio, visit https://docs.nuget.org/consume/package-manager-dialog.

Note

Note that a project created using the ASP.NET Visual Studio 2013 template does not require adding these packages explicitly.

The following figure describes the core assemblies and their dependencies that get downloaded when the Microsoft.AspNet.WebApi package is installed. There are other NuGet packages that are published by the ASP.NET Web API team (such as CORS support, Help Pages, OWIN host). This figure provides the bare minimal to get started with ASP.NET Web API development:

Now, let's look at some of the important runtime types that enable the communication and execution in the ASP.NET Web API pipeline.

DelegatingHandler

As mentioned earlier, the execution of a request implements a Russian Doll Model. A DelegatingHandler is a runtime type that enables the creation of a handler that can participate in the chain of request and response pipeline for ASP.NET Web API. Although used heavily by the ASP.NET Web API infrastructure, DelegatingHandler is a type defined in System.Net.Http.

DelegatingHandler is derived from HttpMessageHandler, which is the abstract base class for all HTTP message handlers. The most critical method exposed by HttpMessageHandler is the abstract SendAsync method. It is responsible for maintaining the chain of the request and response pipeline. DelegatingHandler can enrich the request message before calling SendAsync; once called, it sends the incoming request to the next handler for processing.

protected internal abstract Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken);

DelegatingHandler acts as a base type for built-in message handlers such as HttpServer. In its base implementation, it enables assigning an inner handler during construction and delegating the SendAsync request to the inner handler, thus enabling a chain between the handlers. Any type that inherits from DelgatingHandler can then participate in the pipeline by ensuring that SendAsync on DelgatingHandler is called.

public class CustomMessageHandler: DelegatingHandler
{
    protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        // Call the inner handler.
        var response = await base.SendAsync(request, cancellationToken);
        return response;
    }
}

Alternatively, an inherited type may return a response instead of invoking base.SendAsync. For example, a handler generating a response. Another useful scenario could be where a handler detects an exception and wants to stop processing the request.

Note

Note that the call to SendAsync is asynchronous, thus satisfying the "asynchronous to the core" design principle of REST.

All message handlers in ASP.NET Web API are contained in an ordered collection as part of the HttpConfiguration.MessageHandlers collection. What this means is that the handlers are always executed in sequence of their addition. The ASP.NET Web API framework allows for defining message handlers at the configuration level on a per route basis using HttpRoutingDispatcher. We discuss more details about this feature in the Routing and dispatching section.

HttpRequestMessage

HttpRequestMessage is a runtime type defined in the System.Net.Http namespace; it acts as an unified abstraction for all HTTP requests irrespective of client or server. Any incoming message is first converted into HttpRequestMessage before it traverses through the pipeline; this provides an ability to have a strong type HTTP message throughout the pipeline.

An HttpRequestMessage may contain values for the following attributes:

Name	Description
Method	This specifies the method of the request (GET, POST, PUT, DELETE, OPTIONS, TRACE, HEAD) and returns an HttpMethod type.
Content	This specifies the body of the request. It is contained in an HttpContent object.
Headers	This contains all headers in the HTTP request. These can be used to retrieve authorization headers and user agents. The Content property also exposes a Headers collection, which is useful to define header values for the content itself, such as ContentType and MediaFormatters.
Properties	This represents a dictionary that can contain custom values to be passed as part of the request, such as error details.

HttpResponseMessage

HttpResponseMessage represents the other side of the story and provides an abstraction for all responses generated for corresponding HTTP requests. It is also defined in the System.Net.Http namespace. Any response within the pipeline will be represented as HttpResponseMessage before it gets converted and sent to the caller.

HttpResponseMessage may contain values for the following attributes:

Name	Description
Content	This specifies the body of the request. It is contained in an HttpContent object.
Headers	This contains all headers in the HTTP response. It is a key-value pair collection of the HttpResponseHeaders type.
RequestMessage	This is a copy of the request message (HttpRequestMessage) that leads to the response.
IsSuccessStatusCode	This is a bool value that indicates whether the HTTP response is successful.
StatusCode	The HTTP status code for the response (for example, a 202 status code would mean success) returns the HTTPStatusCode enum.
ReasonPhrase	This is a string description that corresponds to the status code that has been returned (for example, a reason phrase for a 202 status code will be "Accepted").
Version	This is the HTTP protocol version; the default is 1.1, which returns a version type.

HttpResponse also exposes the EnsureSuccessStatusCode method, which is especially useful in testing scenarios where a successful response is expected. The method throws an exception if HttpResponseMessage does not return with a success HTTPStatusCode in the range of 200 to 209. Note that in case of a failure response, the EnsureSuccessStatusCode internally calls Dispose on the stream if the Content property for the response is not null. Essentially, we cannot access the Content stream post with this method when a failure status code is returned.

ApiController

ASP.NET MVC has the concept of controllers since its inception; conceptually, Web API controllers follow a similar approach to leverage the goodies from the ASP.NET framework. However, Web API controllers are targeted towards providing an abstraction over the HTTP request-response pipeline. Moreover, Web API controllers return only response data in contrast to HTML views in ASP.NET MVC.

All Web API controllers implement the IHttpController interface to classify them as Web API controllers. As we will see in the next section, the Web API request dispatch, and route matching pipeline attempts to look for an IHttpController instead of a particular controller implementation. The following code snippet shows the definition for the IHttpController interface.

namespace System.Web.Http.Controllers
{
    public interface IHttpController
    {
        Task<HttpResponseMessage> ExecuteAsync(HttpControllerContext controllerContext, CancellationToken cancellationToken);
    }
}

While we can create our controllers by implementing the IHttpController interface, ASP.NET Web API provides a useful base class that abstracts most of the low-level plumbing required for the request-response pipeline.

A typical APIController.ExecuteAsync implementation looks like this:

public virtual Task<HttpResponseMessage> ExecuteAsync(HttpControllerContext controllerContext, CancellationToken cancellationToken)
{
    if (this._initialized)
    {
        throw Error.InvalidOperation(SRResources.CannotSupportSingletonInstance, new object[2]
        {
            (object) typeof (ApiController).Name,
            (object) typeof (IHttpControllerActivator).Name
        });
    }
    else
    {
        this.Initialize(controllerContext);
        if (this.Request != null)
        HttpRequestMessageExtensions.RegisterForDispose(this.Request, (IDisposable) this);
        ServicesContainer services = controllerContext.ControllerDescriptor.Configuration.Services;
        HttpActionDescriptor actionDescriptor = ServicesExtensions.GetActionSelector(services).SelectAction(controllerContext);
        this.ActionContext.ActionDescriptor = actionDescriptor;
        if (this.Request != null)
          HttpRequestMessageExtensions.SetActionDescriptor(this.Request, actionDescriptor);
        FilterGrouping filterGrouping = actionDescriptor.GetFilterGrouping();
        IActionFilter[] actionFilters = filterGrouping.ActionFilters;
        IAuthenticationFilter[] authenticationFilters = filterGrouping.AuthenticationFilters;
        IAuthorizationFilter[] authorizationFilters = filterGrouping.AuthorizationFilters;
        IExceptionFilter[] exceptionFilters = filterGrouping.ExceptionFilters;
        IHttpActionResult innerResult = (IHttpActionResult) new ActionFilterResult(actionDescriptor.ActionBinding, this.ActionContext, services, actionFilters);
        if (authorizationFilters.Length > 0)
          innerResult = (IHttpActionResult) new AuthorizationFilterResult(this.ActionContext, authorizationFilters, innerResult);
        if (authenticationFilters.Length > 0)
          innerResult = (IHttpActionResult) new AuthenticationFilterResult(this.ActionContext, this, authenticationFilters, innerResult);
        if (exceptionFilters.Length > 0)
        {
            IExceptionLogger logger = ExceptionServices.GetLogger(services);
            IExceptionHandler handler = ExceptionServices.GetHandler(services);
            innerResult = (IHttpActionResult) new ExceptionFilterResult(this.ActionContext, exceptionFilters, logger, handler, innerResult);
        }
        return innerResult.ExecuteAsync(cancellationToken);
    }
}

The series of actions performed by the API controller in the preceding code is as follows:

1. The API controller invokes the action selection logic for the HTTP request.

2. It then initializes and invokes the registered authentication filters.

3. Subsequently, it initializes and invokes the authorization filters.

4. Next, the action filters are initialized and invoked followed by the exception filters in case of exceptions.

5. In the last step, it invokes the Parameter Binding and content negotiation for the requests and responses.

Finally, the operation is executed.

Message lifecycle

Now that we have some context of the main APIs involved in the Web API request-response pipeline, let's take a look at how a request flows through the Web API pipeline and how a response is directed back to the client.

At a broad level, the message pipeline can be categorized into three main stages:

Let's walk through the message pipeline using a sample Web API. The Web API is a simple Hello World API that allows the client to issue a GET request and returns the string Hello world! in JSON. For now, don't worry about the implementation details of this Web API. In the next sections, we will get into deeper detail on how to create, test, and deploy a Web API.

Request	http://localhost:12356/api/hello
Response	Hello world!

Host listener

A host listener refers to a component listening for incoming requests. For years, Microsoft Web Components had an inherent dependency of using Internet Information Services (IIS) as the host. The ASP.NET Web API breaks out of this legacy model and allows itself to be hosted outside IIS. As a matter of fact, we can host a Web API in an executable, which then acts as the server receiving requests for the Web API. There are many options available to host a Web API; we will explore some of them in detail in Chapter 2, Extending the ASP.NET Web API. For now, we will focus on using either of the hosting options and enable listening for requests and responding with a response.

Considering the earlier Hello World example, the incoming request will be processed as shown in the following diagram:

In the preceding diagram:

1. The client code issues a GET request using HTTP 1.1 as the protocol. The request is issued to an endpoint, which represents a resource on the server.

   GET http://localhost:12356/api/hello HTTP/1.1
   Host: localhost:12356

2. The configured host listener will then receive the request and convert it into HTTPRequestMessage. The host inherits from the HTTPServer type, which by itself is a message handler and implements DelegatingHandler. So, essentially it is just another message handler that delegates the request to the next handler (remember the Russian Doll Model we talked about earlier).

3. The request is then sent through to the routing and dispatching components and then to the controller components for further processing and returning the response.

The routing and dispatching stage primarily involves the execution of a series of message handlers, which process the incoming request and then delegate them to the next message handler for processing. In earlier versions of ASP.NET Web API, we could only configure message handlers globally per application. All the message handlers were added to the HttpConfiguration.MessageHandlers collection and were executed for each request. The global configuration was enabled using the Register method in the WebApiConfig.cs file, which gets added when creating a new ASP.NET Web API project. We talk more about the WebApiConfig and Register method in the Creating our first ASP.NET Web API section. The following snippet show a sample Register method definition:

public static void Register(HttpConfiguration config)
{

    config.Routes.MapHttpRoute(
       name: "DefaultApi",
       routeTemplate: "api/{controller}/{id}",
       defaults: new { id = RouteParameter.Optional }
    );
    // add a new message handler to all routes
    config.MessageHandlers.Add(new CustomMessageHandler());
    
}

In the preceding code, we configured CustomMessageHandler() to be called for all routes in the Web API. While this worked well for most basic scenarios, it became a challenge for applications where specialization for a route was required. For example, specific authorization handlers for a route. Web API 2 introduced a per route handler flow that allows granularity when routing requests to message handlers. The following code is added to WebApiConfig.cs to configure a per route custom handler in the ASP.NET Web API 2:

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

    config.Routes.MapHttpRoute(
        name: "CustomDefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional },
        constraints: null,
        handler: new CustomMessageHandler()
    );
}

In the preceding code, we configured CustomMessageHandler, which inherits from DelegatingHandler to a particular route. We also have a global route with API/common that when called will not invoke our custom message handler, it will rather follow a global configuration. The internals of CustomMessageHandler have been omitted since they are not necessary at this stage; all we are concerned here is how the internal routing logic works. We will discuss these concepts in greater detail in Chapter 2, Extending the ASP.NET Web API.

Let's look at how the per-route message handler routing is performed by ASP.NET Web API 2:

In this section, we will start building our Web API, covering the necessary environment required for creating a Web API. We will also discuss our problem scenario, and then create a Web API from scratch. We will then delve into the details of Microsoft Azure websites and deploy our first Web API in Microsoft Azure.

Prerequisites

The following must be configured to run the example scenarios we discuss in this and following chapters:

• Developer machine: We need a development environment that can support Microsoft Visual Studio and ASP.NET Web tools. Although we can create ASP.NET Web API solutions from a local PC, for the purpose of this book, we will host a new virtual machine in Microsoft Azure and use it as our development environment. Setting up and managing an environment on Microsoft Azure is so straightforward and elegant, that it is now used as a preferred way to develop applications.

• A Microsoft Azure subscription: We need a Microsoft Azure subscription to host our Web API. A free trial is available at http://azure.microsoft.com/pricing/free-trial/?WT.mc_id=A261C142F. For MSDN subscribers, Azure subscription can be activated using their Microsoft Azure credits.

• Visual Studio 2013: Once we have the virtual machine up and running, we will need Visual Studio 2013. Any version of Visual Studio Professional 2013 or later should be sufficient for our samples. There is also a free full feature version of Visual Studio referred to as Community Edition, which enables ASP.NET web development. MSDN subscribers can also get access to a set of preconfigured Visual Studio virtual machine images available as part of the Microsoft Azure subscription. The source and samples for this book are built using Visual Studio 2013 Community Edition Update 4.

• Visual Studio Online: It is always good practice to use a code management and collaboration system when starting a project. Visual Studio Online (VSO) is a Microsoft Azure-based service that provides the capabilities of Team Foundation Server in the cloud. We will use VSO for source control throughout all samples, we will also be using Git as our source control system; Visual Studio Online provides integral support for this. VSO also provides integration with Microsoft Azure for Continuous Integration (CI) and Continuous Delivery (CD) capabilities.

A free Visual Studio Online account can be created at the following link: https://www.visualstudio.com/en-us/products/what-is-visual-studio-online-vs.aspx. To know more about using Git with Visual Studio Online, visit the following link: https://msdn.microsoft.com/en-us/library/hh850437.aspx.

An alternative is to use GitHub as a source control strategy as well. For the purpose of this book, we will use VSO and Git.

Now that we have the development tools installed and ready, let's quickly take an example to put these to test. We will build an ASP.NET Web API for a fictitious transport service provider that provides consumers with package tracking abilities. The following figure shows how clients interact with the solution:

Creating the ASP.NET Web API project

We will start by creating a new ASP.NET Web Application project in Visual Studio.

Uncheck the application insights to project box for now.

In the new ASP.NET project page, we select the empty template and check Web API in the Add folders and core references for section. Let Authentication be set to No Authentication for now. The empty template skips many other sample controllers and folders such as the MVC helper and documentation folders.

Also, we unselect Host in the Cloud under Microsoft Azure for now. We will add this in the next section when we talk about the Microsoft Azure website.

At this stage, the solution should look like this:

A few things have been added to jump start our Web API project:

A static WebApiConfig type has been added to the App_Start folder. The WebApiConfig.cs file is responsible for registering configuration settings for the Web API during startup. Some of the common uses of WebApiConfig.cs are to define default routes, customize the behavior of global and per route matching routes, and define media type formatters.

An important thing to note is the Register method that contains the following code:

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

This method defines the default route template for any request; what this means is that any request that has a route api/{controller}/{id} will be considered a valid route. In this route we have the following parameters:

• {controller}: This refers to the name of the controller class without the suffix, for example, a class with name PackageController will be represented as Package in the incoming request

• {id}: This is used for parameter binding, these together define the controller and action route for the request

With Web API 2, we now have the option to specify attribute-based routes on each API call to provide granular route definitions for our Web API. We will cover this in more detail in Chapter 2, Extending the ASP.NET Web API.

The Global.asax file has the following defined in Application_Start, this registers a delegate for the WebApiConfig.Register method in GlobalConfiguration. Note that GlobalConfiguration belongs to System.Web.Http.WebHost, which indicates that we are currently hosting our Web API in IIS, as shown:

GlobalConfiguration.Configure(WebApiConfig.Register);

Now that we have a Web API created, we will look at options to validate our Web API functionality. Testing is a crucial stage in the creation of Web API development and publishing. There are a couple of different ways of doing this. We can just test it by requesting the URL in a browser or write code and leverage the System.Net.HttpClient type. This section discusses both of these approaches.

GET /api/package/1 HTTP/1.1
Host: localhost:49435
Cache-Control: no-cache

In the previous section, we built and tested our Web API. Now, we discuss how to use Visual Studio Online and Git for source control management. Note that this section assumes that we have a Git repository created and available. It does not give a walkthrough of setting up a Git repository within VSO.

We will now commit the change to Visual Studio Online. Visual Studio 2013 provides a rich integration with Git so we can commit the changes without opening the Git command prompt:

Microsoft Azure Websites is a Platform as a Service (PaaS) offering from Microsoft, which allows publishing web apps in Azure. The key focus when building Microsoft websites is to enable a true enterprise-ready PaaS service by allowing rapid deployment, better manageability, global scale at high throughput, and support for multiple platforms. The development of Azure Websites started about 3 years ago under the internal project name Antares with the primary intent to create a cheap and scalable web hosting framework for Microsoft Azure. The main target was shared and cross-platform hosting scenarios. The first preview release for Azure Websites came out in June 2012 and went General Availability (GA) in mid-2013.

There are other PaaS offerings available in Microsoft Azure, such as cloud services that provide Web and worker roles. There is also Microsoft virtual machine through the Infrastructure as a Service (IaaS), so why choose websites?

Let's look at some of the features provided by Azure Websites, which make them an appealing candidate for Web API and web app deployment:

As we can see in the preceding figure, Azure Websites are built on existing technologies, such as Azure storage and web and worker hosting model. It adds additional abstraction to enable rapid deployment and easy configuration management through a set of hosting site and site content databases. Furthermore, Azure load balancers are used in conjunction with IIS Application Request Routing (ARR) load balancers to achieve high availability and Hyper Scale. Azure Websites provides the following benefits:

With such great features, is there any scenario where Azure Websites might not be a good fit?

Well, there are some scenarios where we may be better off using Azure Cloud Services and perhaps even Azure Virtual Machines:

Note that some of the scenarios mentioned here might not be available as of today, but the team may provide support for these in future releases. As a rule of thumb, consider these as recommendations and not protocols. Considerable planning should be conducted based on customer requirements and timelines before making a decision to choose any of the platform options.

Deploying to Azure Websites

Now that we have a fair understanding of Azure Websites' capabilities, let's deploy the Web API we built in the previous section to an Azure Website.

Note

This sample assumes that the user is signed into an Azure account in Visual Studio. It is required to view the Azure subscription when creating the ASP.NET Web API project. For more information on Azure tools for Visual Studio, please visit http://msdn.microsoft.com/en-us/library/azure/ee405484.aspx.

Since we did not associate our Web API project to an Azure Website at the time of its creation, we will now provide details on the Azure subscription and website where we want the deployment to be hosted:

1. Right-click on the Web API project. Click on Publish to open the Publish wizard, and select Microsoft Azure Websites as the publish target.

2. In the Microsoft Azure Websites dialog, click on New to create a new Azure Website. Here, we provide details about our Azure subscription and give a name to the website. When deciding on a name, ensure that it is unique; the Create Site dialog box validates the fully qualified URL to ensure that there are no existing sites with this name. In case the site name already exists, an error is thrown by the Create Site dialog box.

3. By default, the domain name is set to azurewebsites.net. It is the default domain for all tiers; we can also provide a custom domain for our deployments (for example, www.mywebsite.com).

   

4. Once the Website is created, we are ready to publish our Web API. Azure Websites provides the following publish methods for web applications:

   • Web deploy: This is also known as msdeploy. It streamlines the deployment of web application to Azure Websites. It enables the packaging of Web application content, configuration, databases, and any other artifacts, which can be used for storage or redeployment. If the package needs to be redeployed to a different environment, configuration values within the package can be parameterized during deployment without requiring modifications to the packages. Use this option to delegate deployment to Azure Websites.

   • WebDeploy package: We can use this option when we have an existing WebDeploy package.

   • FTP: This allows to deploy source from an FTP server.

   • File system: This deploys source from a local filesystem location.

5. Once the deployment is complete (should not take more than a few seconds), we will have our Web API running in the cloud.

6. To test the deployment, replace the local domain name we used in the Testing in a browser section with the cloud domain name of the Azure Website as shown:

   Request	http://dotnetbook.azurewebsites.net/api/package/1
   Response	{ "Id": 1, "AccountNumber": "ac09ae02-00cf-426d-b969-909fae655ab9", "Destination": "TX", "Origin": "CA", "Weight": 2, "Units": 1, "StatusCode": 1, "History": null, "Properties": null }

If we now browse to the Azure management portal and go to the Azure Website we just created, we can right away see incoming requests and how the traffic is being monitored by Azure Websites similar to how it is shown in the following diagram; now that is true PaaS!

Note

The new Azure portal (currently in preview) provides more detailed statistics about the resources leveraged by Azure Websites. These include storage, network, and compute. The preview portal is accessible at https://portal.azure.com/.

In the previous section, we used Visual Studio tools to deploy our Web API in Microsoft Azure Websites. The Visual Studio deployment option works well for one-off deployments or small development projects. However, in real-world scenarios, customers prefer integrating builds with automated deployments. Azure Websites provides continuous deployment from source code control and repository tools such as BitBucket, CodePlex, Dropbox, Git, GitHub, Mercurial, and Team Foundation Server. We can, in fact, do a Git deployment from a local machine!

For the purpose of this sample, we use VSO and Git as our repository. Let's take a look at how we can configure Visual Studio Online for our Continuous Deployments (CD):

Our Web API is now successfully deployed in Microsoft Azure Website and configured for CD.

This chapter provided an overview of the what, why, and how of an ASP.NET Web API. ASP.NET Web API is a next generation service that enables support for a first-class modern HTTP programming model. It provides abundant support for formats and content negotiation, and request validation.

We talked about the foundational elements of a Web API. We then discussed its usage scenarios and components, and also discussed the classes that make up the API. We went through the request-response pipeline and walked through the message lifecycle of a request. We then created our first simple Web API for a simplified customer scenario and walked through its development, testing, and deployment using Azure Websites. In the next chapter, we will look into advanced capabilities of ASP.NET Web API, and see how these capabilities can be used to customize different aspects of the ASP.NET Web API request-response pipeline.