Another Azure Functions and Cosmos DB Graph API blog

As soon as our partners in the Cosmos DB team released the Graph API earlier this year I knew I would have to build a demo leveraging Azure Functions and Azure Functions Proxies to interact with a graph data model.

This blog includes a sample that creates a generic REST API on top of Cosmos DB Graph API as well as a sample Web page to interact with it.

What you would need to make the solution work

To get this sample working you would need:

An Azure Subscription
Git client (GitHub account is recommended)
Visual Studio 2017 Tools for Azure Functions installed

Why is your demo different than other blog posts?

Great question! The Graph API uses Gremlin syntax to interact with a Graph. I figured it would be nice if we can easily write a REST API that performs simple CRUD operations against a Graph.

Problem we are trying to solve

Consider a simple Gremlin query to add a new Vertex to a graph. You would need to connect to your Cosmos DB and send it a string that looks like:

g.addV('Vertex Name').property('id', 'Vertex ID')

What you would want is a REST API that looks like:

https://MyRESTAPI/api/{Cosmons DB Collection}/vertex/add/{Vertex ID}/{Vertex Name}

So this is really about constructing a REST API path, mapping the pieces of the URL path to a Gremlin expression and sending this expression to Cosmos DB.

Creating the REST API

Since coding is not really my core competency I was looking for a way to have as little code as possible and be able to add APIs using a declarative format. This is where Azure Functions Proxies came to the rescue! With Proxies we can map many URL path to on Azure Function, the Function can then investigate the incoming data and assemble the Gremlin expression.

The sample app includes:

A Cosmos DB database
An Azure Function
A Proxies json file
A query map json file used to generate the Gremlin queries
An HTML\ Java Script file used as a test client

Setting up the sample

Create a new Cosmos DB database (you can use an existing one if you want). To create a new Database:

Follow the steps in this link to create a new Database. No need to follow the other steps in the doc. Note: Graphs will be automatically created if they don't existing within the database. The term Graph and Collection interchangeable in this blog

Copy the database name, URI and one of the keys in the Keys screen of your Cosmos DB Database (click the Keys menu item on the left for the URI and key values). You will use them later.
Create a new Azure Functions App.
Go to the Platform features tab and create 3 new App Settings in your new Function App by following the steps here and here:

Endpoint
AuthKey
databaseName

Fill in the values you copied in step 2 into your Function App Settings:

Endpoint will be the Cosmos DB URI
AuthKey will be the Cosmos DB key
databaseName will be the Cosmos DB Graph name

Enable Azure Functions Proxies (currently in preview)
Clone the sample GitHub repository locally

git clone https://github.com/nirmash/CosmosDBGraphREST.git

and browse to the code folder

cd CosmosDBGraphREST\CosmosDBGraphREST

Open GraphFunc.sln (should be in the CosmosDBGraphREST folder) in Visual Studio 2017.
Right-click on the GraphFunc solution and select Publish. Click the "Select Existing" radio button and hit the Publish button.
Find the Functions App you created in step 3
Browse to your test page

https://{Function App Name}/GraphUI

Your REST API should now be up and running!

Loading some data into your graph

Use the curl commands below or just paste the Urls in a browser to load a bit of data into your graph. In this case, a car brand and car types belonging to this brand. A graph named "cars" will be created in your Comsmos DB database.

curl https://{Function App Name}/cars/addvertex/Audi/Brand
curl https://{Function App Name}/cars/addvertex/A4/Sedan
curl https://{Function App Name}/cars/addvertex/A6/Sedan
curl https://{Function App Name}/cars/addvertex/Q5/SUV
curl https://{Function App Name}/cars/addvertex/Q7/SUV
curl https://{Function App Name}/cars/addedge/Audi/A4/Sedans
curl https://{Function App Name}/cars/addedge/Audi/A6/Sedans
curl https://{Function App Name}/cars/addedge/Audi/Q5/SUVs
curl https://{Function App Name}/cars/addedge/Audi/Q7/SUVs

Now to run a couple of queries against your new graph! To see all the items (Vertex) in the graph, type the below in a browser:

curl https://{Function App Name}/cars/selectcollection

To see all the cars in the graph that are defined as Sedans:

https://{Function App Name}/cars/selectedgeout/Sedans

You will see a JSON string coming back like the below:

[
  {
    "id": "A4",
    "label": "Sedan",
    "type": "vertex"
  },
  {
    "id": "A6",
    "label": "Sedan",
    "type": "vertex"
  }
]

What's next?

This blog suggested a way to take the generic Gremlin query language and use an Azure Function and Azure Functions Proxies to create a REST API that performs CRUD actions against Cosmos DB Graph API collections. There is plenty of information out there about Azure Functions, Azure Functions Proxies and Cosmos DB. Leave me comments or questions and play with the code!

nirmash / CosmosDBGraphREST