Building a Custom API for PowerApps using Azure App Service Web Apps

Carlos Aguilar, Partner Group Software Engineering Manager, PowerApps, mercoledì 8 giugno 2016

One of the most powerful features that PowerApps offers is the ability to extend its capabilities by creating Custom APIs. Custom APIs are normal REST APIs that expose some functionality. Whether you are trying to build some complex logic or connecting to your existing systems, you can simply create a REST API in your favorite platform using any language, describe it using Swagger and use it in PowerApps. We support a few authentication mechanisms such as Azure Active Directory and Basic Authentication, and will add others over time.

The purpose of this blog is to show you how easy it is to build a Custom API using Azure App Service Web Apps and consume it in PowerApps.

Azure App Service Web Apps is a managed compute environment that provides a very powerful platform for building and hosting sites, web applications, APIs and more. It allows developers to use their favorite development tools and programming languages, including C#, Java, Node.js, PHP, Python and more. It has a rich set of advanced features such as continuous delivery support with Git, GitHub, Dropbox, VSTS and others, multiple slots (for scenarios like managing multiple environments, A/B testing, etc.), on-premise connectivity, SSL, custom domains, FTP, analytics, and much more.

Did I mention that you can use it for free? App Service will give you 10 free web sites, so go and create your subscription here. To develop the API below you can use Visual Studio Community 2015 or Visual Studio Code which both are free for you to use.

What we’ll be building

In this example, we will build a REST API using ASP.NET Web API in C# that includes an endpoint called HRApi that will return a list of employees. To keep it simple we will keep those records in a list in memory so that we can focus on how to put the API together and not get distracted with the specific technologies for data access.

At a high level the steps we will follow are:

Use Visual Studio to create the REST API
Deploy the API to Azure App Service
Register the Custom API to use in PowerApps
Build a PowerApp that consumes the API

Build the Web API using Visual Studio 2015

REST APIs can be created in any platform and any language. In this case we will use ASP.NET Web API since it provides a framework that makes it very easy to build REST API/services. The main class for building ASP.NET Web API services is called ApiController.

Create the API Controller

Launch Visual Studio 2015 and select File->New Project
Select the template Visual C#->Web->ASP.NET Web Application. In this case I will call my API “HR”.

You can use different templates to build an API such as Empty, MVC, WebAPI, and Azure API App. Each of those templates adds additional references and files to help get you started quickly with different scenarios. In this case I will choose the Empty template to show that it is very easy to build one from scratch. So select the “Empty” template and check the “Web API” checkbox in the “Add folders and core references” so that it adds a reference to the assemblies required to use Web API. Click Ok.

Now we will add an API controller to implement the logic. For that, right click the “Controllers” folder in Solution Explorer and select the option Add->Controller.. “We’ll use the “Web API 2 Controller – Empty” option, and we’ll call it “EmployeesController”. There are several templates you can choose to get started such as ones that will help you generate CRUD APIs using Entity Framework and others.

Copy and Paste the following code.

using Swashbuckle.Swagger.Annotations;
using System.Collections.Generic;
using System.Web.Http;
namespace HR.Controllers
{
    public class EmployeesController : ApiController
    {
        [SwaggerOperation("GetEmployees")]
        public IEnumerable<Employee> Get()
        {
            return employees;
        }
        public class Employee
        {
            public string ID { get; set; }
            public string FirstName { get; set; }
            public string LastName { get; set; }
            public string Title { get; set; }
        }
        static List<Employee> employees = new List<Employee>()
        {
            new Employee() { ID = "01", FirstName = "Employee 001", LastName="LastName 01", Title = "CEO"},
            new Employee() { ID = "02", FirstName = "Employee 002", LastName="LastName 02", Title = "CTO"},
            new Employee() { ID = "03", FirstName = "Employee 003", LastName="LastName 03", Title = "CMO"},
        };
    }
}

The code above defines a type called Employee and holds a list of three employees in a list in memory. It also includes a method called “Get” that is exposed through swagger as “GetEmployees”.

Add Swagger support

Swagger is a JSON format that helps describing the operations (paths), responses and parameters that a REST api has. You could spend a long time authoring JSON/swagger manually or using tools on the web for converting YAML to swagger, however, one big challenge with that is that it tends to diverge from the actual code, or you can easily have typos and have an invalid API definition. One great thing about using .NET and its strongly typed model, metadata and reflection capabilities is that it allows for tools to easily inspect the code and auto-generate things for you. In this case, we will use Swashbuckle, a great package available in NuGet that can auto-generate Swagger based on an API Controller. This way it will always be kept up to date and correct. To do that follow the next steps:

In the Solution Explorer panel right-click the “References” node and select “Manage NuGet Packages” option.
Select the “Browse” tab, and search for “Swashbuckle” and install the latest version (at the time of this write up it is 5.3.2)
And that is all you need to do. To test, just press “F5” and it will launch a browser and navigate to the root “/” directory. You will encounter a “403.14” Forbidden message since there is content at the root of the site, so instead add “/swagger” to the URL. This route is handled by Swashbuckle to automatically generate a User Interface where you can view and test your swagger, and exercise your API.

Deploy to Azure App Service Web App

To deploy to Azure App Service you will need to create an Azure Subscription first, and you can do that at here, where you can get a perpetual free tier for services such as Azure Active Directory, Web sites on App Service, and more, as well as a free trial for other services such as Virtual Machines, etc. Once you have created your subscription, you can go back to Visual Studio and continue with the following steps.

Back in Visual Studio, in Solution Explorer right-click and select Publish…
In the “Publish Web” dialog select the option “Microsoft Azure App Service”

publish-web

In this dialog you can choose an existing Web App that you want to deploy to, but in this case I will create a new one, so select the option “New…”
Enter all the details about your subscription and resource group. In my case I will use hrapi as the name of the API which will be part of the URL to access the service such as http://hrapi.azurewebsites.net:80/swagger/docs/v1, and click publish, that will create a new Web App and deploy the retail version of your code using Web Deploy.

Configure Custom API in PowerApps

To configure a Custom API in PowerApps we will need the Swagger file to describe the REST API and an Image to use as the icon for the API. To get the swagger you can navigate to the Web App you created and add /swagger just as we did locally. In that User Interface you will see a URL at the top which should look something like: http://hrapi.azurewebsites.net:80/swagger/docs/v1 (just replace the hrapi for the name you used when creating your Web App). Navigate to that URL and save the contents as “HRApi.json” on your machine.

To register a Custom API in PowerApps simply navigate to https://web.powerapps.com/#/connections/available/custom/create, or navigate to https://web.powerapps.com and click Manage->Connections->New Connection->Custom->New Custom API
Click Next. In this case we are not using any Authentication so we can just click Create. This will upload the Swagger and register a new Connection Provider for you to be able to create connections.

Using the new Custom API in PowerApps

To use the newly created Custom API, just:

Summary

In this example we saw how easy it is to create a REST api using ASP.NET Web API and deploy it to Azure App Service Web Apps, and how to use Swashbuckle to automatically generate the right Swagger to describe the API so that it can be used in PowerApps as a Custom API.

One final note: It is worth calling out that the sample above is accessible using anonymous authentication. Azure App Service has the ability to protect your App Service web apps using Azure Active Directory which you can learn more about here.

Launch PowerApps Studio
Create a new PowerApp, in my case I used New –>Blank App –>Phone Layout
Go to the Content option in the ribbon and click DataSources.
In the Data sources panel click the “Add data source” button, click “+ Add Connection”, and select your Custom API. Click Add Data source.
Once you add it, PowerApps will expose the all operations in the API as new functions that you can use that behave just like any other built-in functions but that will asynchronously execute the correct HTTP request to call your API. In this case add a Gallery (Click Insert->Gallery->Vertical), and in the formula for the Items property start typing HRAPI which will help you listing the APIs