AzureCon Challenge

Using Azure API Apps

Overview
A very common application pattern, especially in the multi-platform mobile world, is for applications on devices to talk to back-end services using standard
REST based approaches. Its becoming more common to just take this approach to connect various application components and logic as well simply
exposing application logic using a REST based API.
In this challenge, you will build a simple API that represents some business logic in an application. You will then consume this API from another application.

1. Login to Azure
For this challenge, you have either elected to use your own subscription or have created a new Azure
subscription using the provided Azure Pass (or Free Trial). If you want to switch to use the provided Azure
Pass the promotion code is displayed on the My Account page on the http://challenge.azurecon.com web
site. If there is no promo code displayed, you will need to use the free trial http://azure.microsoft.com/pricing/free-trial.
Azure has TWO management portals - the classic portal (http://manage.windowsazure.com) and a new
portal that is in Preview at http://portal.azure.com. You will use the Preview portal in this challenge.
1.

Open a browser and go to http://portal.azure.com

2.

Enter your Microsoft Account email address and password for the Microsoft Account you
associated with your Azure Pass or your own subscription.

3.

You will now be in your Azure subscription (see opposite) and from here you can create and
manage Azure services.

2. Ensure you have everything! This lab requires Visual Studio.

1.

If you do not have Visual Studio installed, you can easily create a virtual machine that has it ready. Use the following steps to provision a Visual
Studio Virtual Machine if you need Visual Studio. If you have done this in a previous challenge, you can use that Virtual Machine. If not, skip this
section.

2.

Using the Azure Preview Portal (http://portal.azure.com) click +New -> Compute -> and then Marketplace

3.

In the Search Box, enter Visual Studio Community 2015, click the Visual
Studio Community 2015 with Azure SDK 2.7 on Windows Server 2012 R2
image and press ENTER

4.

Change the deployment model to Resource Manager and click Create.

5.

Name the virtual machine vsDevBox, and specify a user name and a password you will remember (write it down!). Specify the resource group as
vsDevBoxRG and pick a location that is close to you, and then click OK.

6.

Choose a virtual machine size, either A2 or D2 will work. Click OK.

7.

Accept the default settings by clicking OK, Click OK on the summary page to create the virtual machine.

8.

After the virtual machine is provisioned (it will take around 5 minutes), you will connect to it but you can move on with the next section now.

3. Create your API App Service in Azure

1.

Page | 1

In the Portal, click + NEW and then select Web + Mobile and then API App

2.

For API App Name, enter a name such as your alias followed by .webapi so if your email is bsmith@contoso.com you would enter
bsmith.webapi (The API service allows periods but not other symbols).

3.

In the Create new App Service Plan, enter webapiASP.

An App Service Plan is a unit of billing and scaling you can have multiple web assets like web apps, mobile apps etc in the same ASP.

4.

Leave Pricing Tier the default

5.

Click on Create New link in the Resource Group section you want to put your apiapp in a different group to your dev box (if you are creating a
VM for this challenge). Enter webapiRG as the name of your new resource group.

6.

Click on Location and select ANY location you like it does not have to be near you, in fact its fun to pick anywhere in the world just because
you can right?

7.

Click CREATE.

8.

Wait for the API to provision - you will be taken to the portal Home page and a tile will show your API App creating. When it is complete (about
60 seconds) a new blade for your API App will open.

9.

In the blade, in the SUMMARY section, click the API Definition. A new blade will open showing the various API endpoints that can be called. Of
course, the blade is empty (or you get an error) you have not BUILT an API yet all you have is the underlying infrastructure that will run your
API code.

4. Connect to Your DevBox (if you did step 2, if not skip this section)
1.

Click on the Microsoft Azure logo on the top left of the Portal. This will take you to the startboard.

2.

Your devbox VM should be in running state now, click the tile and at the top of the blade, click the Connect button. Depending on your
browser, you will get some sort of download notification about an .rdp file. If you are running on a Mac, you will need to install the Microsoft
Remote Desktop Client from the App Store.

3.

Open the file and follow the prompts to connect. You will need to enter your credentials for the machine you are connecting to at some point.
These are the username and password that you entered when you created your VM. Accept any security warnings.

4.

Click the RESTORE button on the Remote Desktop Connection Bar at the top of your screen.

5.

On the new smaller window, right click the remote desktop application icon at the top left and then in
the context menu, select Smart Sizing. This puts your remote connection window into a resizable state so
the desktop resizes to the window size.

6.

At this point you have a ready, working computer at your disposal. You need to activate the installed copy
of Visual Studio and there is a VS icon on your desktop. Double Click it.

7.

Be Patient ! ! it will take a few minutes for Visual Studio to do its thing and eventually you will see the
VS Sign in screen. You need to sign in (using a Microsoft Account) or Visual Studio wont let you complete setup.

8.

Select your dev setting (e.g. C#) and click Start Visual Studio button. Wait a bit more and you will be ready to move on

5. Create Your API

The modern API approach is to use REST a simple, http based protocol that you hang your business logic off. Since http has various verbs (Get,
Post, Put, Delete etc.) these are used to map to underlying business logic in your APIs. You will create a simple API that returns a list of contacts. So
this maps to the GET http verb since you will be requesting data from the API.
1.

In Visual Studio, click File -> New Project.

2.

In the templates section, click on WEB and select the ASP.NET Web
Application template

3.

For the Project Name, enter myAPI and click OK

4.

In the New ASP.NET Project dialog that comes up, select Azure API App
(Preview) and click OK. It will take a minute or so for all the project packages
to download.

5.

In Solution Explorer (the top right window), expand the Controllers folder.
Right-Click the ValuesController.cs file and select DELETE. This is a default API that just echos some data back you will create something a
little more useful.

Page | 2

6.

Right-Click the Controllers folder and select Add -> Controller. Select the Web API 2 Controller Empty and click ADD.

7.

Name the controller APIController and click ADD.

Controllers (and functions within your controllers) are where your code lives, but there needs to be some way for a call to a specific URL to find its way to the
right function in your code. A new technique in Web API 2 is to use Attribute Routing. This is simply decorating your code functions with some
instructions to help this mapping happen.
8.

First lets turn OFF the old way convention based routing the Web API template actually
implements both types of routing. In Solution Explorer, expand the App_Start folder and
open the WebAPIConfig.cs file.

9.

Select the 5 lines of code that represent the config.Route.MapHttpRoute function and
press Ctrl-K Ctrl-C the will comment out the selected lines.

10.

Go back to your new APIController (just click the tab at the top of your window).

11.

You will create a very simple controller and use the new attribute routing commands so you
can understand how this works. Copy/Paste in the following code within your APIController class.

[Route("api/SayMyName")]
[HttpGet]
public string EchoName()
{
return "My Name is xxx";
}
The ROUTE attribute determines the url used to map into your EchoName method and the HttpGet attribute determines the http method used to
map into your function.
12.

To test this, click Debug Start Debugging.

13.

A browser will launch and initially you will get a 403 error the browser was trying to find a default
page on your local web server. Of course, no default page exists. In the url, append
/api/saymyname and press Enter

14.

You will see a dialog at the bottom of the browser to open saymyname.json click OPEN. Your file will
open in Visual Studio and you will see the text returned from your function. JSON is a file format that is commonly used in to exchange data
between REST services.

(note that behavior may vary in different browsers for example Chrome will send an XML accept header and the API will be
returned as XML rather than JSON. If possible use Edge browser or Internet Explorer).
15.

Close the JSON and file and select Debug -> Stop Debugging.

Normally, you would have a bunch of methods within a controller and many controllers. You
can attribute your whole class with a prefix and then methods as well.
16.

Modify your class so it looks like this opposite. You need to add the
[RoutePrefix] command above your Class definition and you need to change
your SayMyName route to remove the /api prefix.

17.

Now, ALL the methods in your APIController will need to be accessed with /api and
then to get to your EchoName method, you append that route name - so you
would append /api/saymyname

18.

Press F5 and test it works.

19.

Then click Debug -> Stop Debugging.

Thats the basics of Web API and attribute routing. Before you make your API more complex,
you will get your API code published to your API Service on Azure.

6. Publish your API to Azure

1.

In Solution Explorer, right click your myAPI project folder and select Publish (not the solution itself the project!)

2.

Click the Microsoft Azure API Apps (Preview) publish target and then click the Sign-In button use your Azure credentials that you used to
sign in to the Azure Portal.

Page | 3

3.

After sign-in, you will see a dropdown list of existing API Apps your API App you created earlier will be there select it and click OK. A
bunch of settings for your API and retrieved and you can then click Publish.

4.

After publishing, Visual Studio will try and download a file containing a link to your web api close the download dialog.

5.

In the Output Window in Visual Studio, you will see a link to your API COPY this link

6.

Open a new browser window and PASTE in the link.

7.

Add to the url the path to your api which is /api/saymyname and press Enter. You will get a 403 Error why? Well the API service is by
default protecting access to the API you can change this.

8.

Switch to the Azure Preview Portal and click the Microsoft Azure logo to go
to the StartBoard, then click the tile for your API app.

9.

Click the API definition tile you will see your single SayMyName operation.

10.

Click the Settings button on the blade header

11.

Click on Application Settings and change the ACCESS LEVEL from Internal to
Public (anonymous). Click SAVE.

12.

Switch back to your browser session with your 403 error and REFRESH it. You
should now get the Open/Save dialog for your .json file. Click OPEN and you
will see your new JSON file.
If you were using Chrome, you would see this instead:

API Apps also have SWAGGER UI integration. Swagger is an open source framework that enables easy documentation and discovery of your API. By default,
it is NOT enabled. So lets enable it and see what it looks like for your simple API.
13.

In Visual Studio, under your API project, expand the App-Start folder and open the SwaggerConfig.cs file. Press Ctrl-F (Quick Find) and type
enableswaggerui in the search box. DELETE the two comment lines that surround the statement as below:

14.

Publish your project again to your API Service (Right-Click the API Project
and select Publish).

15.

Once published, open the root URL to your API Service and append
/swagger to the URL. You will see a page like this.

16.

Click on List Operations and then click GET. You can even test out the API
using Swagger without building a test client.

Theres much more to the API service than you got to experience in this
short code challenge but hopefully you got a feel for how it can help you focus on what is really key just writing your API code and not have to
worry about the underlying infrastructure that keeps your API working.

--- END OF LAB --Go back to the AzureCon Challenge web site (http://challenge.azurecon.com) and complete the challenge question to get your points.
REMEMBER: You only have one chance at the question, make sure you really know the answer!

Page | 4