It has been a long time since I last created a post here. It is not a question of desire, more of time. In the past two months, I served as Best Man at my youngest brother’s wedding on September 30 and then, two weeks later, I married my girlfriend Woo of four years. We only just got back from the honeymoon. I must say, I was thankful my many years in consulting taught me how to organize and plan; I ended up doing the lionshare of the wedding planning and, I will say, using Agile and Scrum to plan it made it a snap.
These events did force me to forgo speaking for the last 6 months of the year, mercifully in a way as West Monroe has kept me impressively busy. But now, with all of this behind me I can finally turn my attention back to speaking and community involvement. To that end, I will be returning to Codemash in January to speak on React, Redux, and Redux Observables (our team has been using this extensively in our current project).
To that end, I have been wanting to create a new source of data for my future talks and so I decided on cataloging the various StarCraft units. My hope is, in addition to serving as a data source, I might be able to use it also practice Machine Learning to calculate new build orders.
Anyway, to build this API I decided to take a new tactic and leverage Azure Functions with HTTP Triggers and the “new” Azure CosmosDB (the successor to DocumentDb). I thought I would walk through things here:
Creating the CosmosDb
Setting up the backend database was very easy. I simply searched in the Azure portal for Cosmos and followed the steps for setup. I wont get into throughput settings or anything like that as I dont see this being used that heavily.
Create the Azure Function to Create
This ended up being the hardest part, mainly because my Azure CLI tools were out of date and it caused a weird bug when running locally – the request would always come through as a GET – which sucks if you are expecting POST and looking for BODY content. Once I upgraded the problem went away. Just an FYI.
So, Visual Studio tooling has come a LONG way in this aspect, its super easy now to create these Azure functions locally, test them, and seamlessly deploy them. I recommend creating the solution after the project as a whole and using the the “projects” to partition off the various pieces of your API.
In my case, I went with StarcraftApi for my solution name and created AdminApi which will hold admin functions ( in this example we will create a unit ). You can also create class library projects to share logic between the various APIs – hint you will want to make sure these class libraries using the same .NET Standard setting as the Azure function project (AdminApi).
I try to isolate a single Azure function for each file here so, CreateUnit for this example. The goal here is to take take the contents of the incoming BODY and insert the Json into my CosmosDb. You will remember that Cosmos is a NoSQL database so there is not defined schema you need to follow.
Ok, so if you actually look at one of these functions there is a lot to take in, especially in the method signature portion.
- FunctionName – this is for Azure and discovery – it gives the “name” for this function, since Run isnt very descriptive
- HttpTrigger – indicates how the requested is given to the function. In this case, via a Http POST request matching the route api/Unit (case insensitive)
- Admin here indicates that the _master key must be passed to this function to authenticate usage
Once you have these in place you can upload the code to Azure and it can be executed. You can also run it locally though, be aware, the local server does NOT seem to check for Admin creds; I think that is intentional.
When you create your CosmosDb you will be given a connection string. Cosmos fronts a variety of different NoSQL Database technologies, for my example I am using Mongo, so I will have a Mongo connection string and use the Mongo .NET libraries to connect (MongoDB.Driver v2.3.0 – v2.4.x seems to have a known bug where it wont connect properly).
So, the weird thing here is, even though we have a CosmosDB we do not actually have a database. I mean, easy to create you can click +Add Collection and it will prompt you for the database at which point you can do “Create New”.
Collections are where the data will actually live and collections live in databases. Like I said, not hard just very weird when you think about it. But it is a similar paradigm from SQL Azure, where you had to create the server first and then database; just the naming is weird here.
Full sample that I used is here: https://stackoverflow.com/questions/29327856/how-to-insert-data-into-a-mongodb-collection-using-the-c-sharp-2-0-driver
Happy Coding. Hit me in the comments if you have any questions.