Tuesday, October 10, 2017

Build a Node.js RESTful API and deploy it to an App Service in Azure


This post is a rework of the Microsoft documentation Build a Node.js RESTful API and deploy it to an API app in Azure linked with this git hub sample Azure-Samples/app-service-api-node-contact-list
In comparison with the Microsoft documentation, I focused more on the detailed steps with a lot of screen shots and didn't change nothing to the git hub sample so that the reader (even a newbie) can obtain a node.js api running in Azure within a few minutes. This quickstart shows how to :
  • create an Azure App Service to host your API
  • create locally a REST API, written with Node.js Express, using a Swagger definition
  • deploying it on Azure.

Configuring your environment

  • Create your Azure free account. Microsoft will ask for a credit card information for that...
    But, better, if you don't have an Azure Free account and don't want to use a credit card, I recently post an article to test Node.js deployment into an Azure App Service using the super cool "Try Azure App Service" Feature. It's here...
    This feature doesn't offer all the possibilities of an Azure Free Account, but it could be a good start for discovering Azure and Node.js deployment in it.
    If you already have an Azure account or want a more professionnal environment for testing, just continue this post, if not switch to the other one.

  • Download and install Visual Studio Code
  • Download and install Git The most official build is available for download on the Git website. Just go to http://git-scm.com/download/win and the download will start automatically. Once git is installed open a command prompt or powershell and type:
    git -- version
    you should get a similar result:

  • Download node.js and install it
    On this step again you can test installation by asking for the node.js and npm version

Creating an Azure App Service to host the REST API

Connect to Azure portal We are going to host our Node.js REST API into an Azure Mobile APP. From 2015, all the repositories for Web App, mobile App backend, Web API have been gathered in an Azure offering called App Service in order all enjoy the same capabilities (behavior, insights, features,etc.). That means also there are quite the same and you can use a Web API App Service for a mobile backend and vice versa or a Web App App Service for hosting a Web API. So let's create a Mobile App App Service.

Click on App Service in the left menu (1)
Then on Add on the top menu (2)
Finally on the create button for the Mobile App (3) (You notice that Microsoft makes a special advertisment for this type of App Service)

You are then invited to enter the first settings of your App Service before launching its creation within the Azure portal.
Note carefully the App Service name and the Resource Group Name because we need them later for the deployment.
In my case: App Service Name : Contact-list Resource Group: tutorials

Once the App Service is created, locate the deployment credentials blade and fill the required fields then click on save on the top menu.

For having the complete information to deploy we need the Url for Git deployment.
We are first going to initialize the Git capability using the Azure CLI
Open the Azure CLI by clicking the top icon (1)
Accept the creation of the storage for the persistance
Choose Bash mode
When connected to CLI type the following line :

az webapp deployment source config-local-git --name <your app service name> --resource-group <the associated resource group name> --query url --output tsv

in my case

az webapp deployment source config-local-git --name Contact-list --resource-group tutorials --query url --output tsv

The Azure CLI provides you with the Git Url and this Url now appears in the UI in the properties blade:

Testing the Node.js API Locally

We are now going to dowload the Git Hub sample and make it work on our local machine.

Go to the Git Hub sample and download it.

open the sample with Visual Studio Code

Notice that the key files of the project, package.json and server.js are located int the following path: project/end/ContactList

Open a command prompt and navigate to this location, then type the following instruction:

npm install

You should have more lines because it would be your first installation of the npm packages linked to the project.
Once it's done you can test locally by typing this instruction in your command prompt:

npm start

Node is starting a virtual web server and excuting the project on the 8000 port as specified in the server.js file.
So for testing, open Chrome (IE will download the json result as a file) ans type the following Url in the browser:


The browser will display the contact list in a json format:

Deploying to the Azure App Service and testing

Within Visual Studio code, open the integrated terminal

Navigate to the contactlist folder and to initialize your git,type:

git init .

You will notice that a .git folder was created on the contactlist repositery:

Create then a gitignore txt file in the contactlist repositery and type the folowing instruction in it:


Save it and we are going to use a workaround to create a .gitignore file (because windows requires a file to have a name and not just an extension). While holding the right shift key of your keyboard, right click the file and click on "open a windows powershell (or command depending on your windows version) from here:

Then, type:

ren gitignore.txt .gitignore

Then you can notice in VS Code that the gitignore file has the proper icon and that the files under the node_module directory won't be deployed by typing:

git status

on the Visual Studio Code Terminal.

then type

git add .


git commit -m "initial version"

then connect to the Azure App Service by typing:

git remote add azure <git url that you can copy from the porperty blade of your app service>

in my case:

git remote add azure https://deploy-account-02@contact-list.scm.azurewebsites.net:443/Contact-list.git

The terminal just jumps to another line (my screen shot is wrong)
Then push your project files to your App Service by typing:

git push azure master

You are asked for your deployment account credentials,

then your files are deployed:

You can then test by calling your api. Your Azure App Service Url is at the top of the properties blade:

So, in my case one of my API url is:


If you want to have a more complete testing experience using swagger, type this Url:

http://<your app service url>/docs/?url=%2Fswagger#/Contacts

in my case:


Keep developping online within Azure

Last, you can enjoy the preview of Visual Studio Code online for keeping developping your API without having to deploy anymore from local environment.

By the way, it is an excellent way to check what was exactly deployed into the Azure App Service. The deployment has drammatically simplified the solution.

Hope that helps :-)

Videos on the topic:
Deploy a Web App with Node.js from Github on a Mac into an Azure App Service


Scott R. Jones said...

Thank you for writing this article. The original MS article wasn't up to their usual standards.
Would you consider moving this to a GitHub page? If you did, I'd be able to help with any translation issues.

Marc Charmois said...

Hi Scott,

Thanks for your nice comment and proposal,
I will do that with pleasure!


Marc Charmois said...

Hi Scott,

I posted a sample even much more simple on github and used this time a free one hour "Try Azure App Service" feature to host it!


Anonymous said...

Hello Marc. Thanks for a nice post.
Is there any example of this but using a documentdb database?