__.createDocument(
  __.getSelfLink(),
  { name: "Oppenheimer" },
  function (err, newDoc) {
    __.response.setBody(newDoc.id)
  });

This JavaScript creates a new, hard-coded document in the collection with “Oppenheimer” as the name value. The callback responds to the caller with the unique ID assigned to the document. If you’ve worked with JavaScript libraries like Lodash or Underscore.js, the double underscores in this example will feel familiar. However, if you haven’t worked libraries like those, the __ symbol might be off-putting. What is that?

Well, the __ symbol is just an alias for some important objects in the Cosmos DB server-side model. When you read other articles about authoring Cosmos DB stored procedures, you’ll sometimes see code expressed in a more verbose form. Here’s the same code shown above without using the __ alias:

var context = getContext();
var collection = context.getCollection();
collection.createDocument(
  collection.getSelfLink(),
  { name: "Oppenheimer" },
  function (err, newDoc) {
    context.getResponse().setBody(newDoc.id)
  });

Comparing the two versions side-by-side will help you understand how the __ alias works. There’s nothing right or wrong about either style. My advice is to use the one that gives you better comprehension. For me, the __ alias helps to clear away the visual clutter which improves my understanding when I’m composing server-side code in Cosmos DB so I use it all the time. In this example, the __ alias is being used for three operations:

• Creating a new document – __.createDocument(),
• Getting the address of the current collection – __.getSelfLink(), and
• Sending a response back to the caller – __.response.setBody().

The intent of the code is to create a new database document and return the assigned unique identifier back to the caller. So calling __.createDocument() and __.response.setBody() to get those tasks accomplished makes sense. However, you may be wondering about that __.getSelfLink() call. What does that do? What is a self link, anyway? You can think of Cosmos DB links as unique addresses that refer to various objects in the ecosystem. Every object in Cosmos DB has a link. Databases have links. Collections have links. Documents have links. Attachments have links. Every linked object maintains a link to itself which are called a self-links, of course. As an example, here’s a simple document as it might be stored in Cosmos DB:

{
    "message": "Hello Cosmos DB",
    "timestamp": "2018-09-08T21:01:25.494Z",
    "id": "bbd8d3db-8655-a7da-286e-50586cd39289",
    "_rid": "KqgHAMaKS9QBAAAAAAAAAA==",
    "_self": "dbs/KqgHAA==/colls/KqgHAMaKS9Q=/docs/KqgHAMaKS9QBAAAAAAAAAA==/",
    "_etag": "\"0100b33c-0000-0000-0000-5b9438a60000\"",
    "_attachments": "attachments/",
    "_ts": 1536440486
}

Line 6 shows the self-link to the document, appropriately named _self. Let’s look at the shape of the document self-link:

dbs/{db_id}/colls/{collection_id}/docs/{doc_id}/

If you have a document link in hand, its self-link is the document link minus the docs portion:

dbs/{db_id}/colls/{collection_id}/

And similarly, the collection’s database link is its self-link minus the colls part:

dbs/{db_id}/

Now it’s time to make the code snippet deployable. To transform it into a valid stored procedure, first place it into a parameterized function:

function(doc) {
  __.createDocument(__.getSelfLink(),
    doc,
    function (err, newDoc) {
        __.response.setBody(newDoc.id)
    });
}

Instead of saving hard-coded documents about Oppenheimer, we can call this stored procedure to save any sort of JSON document to the collection. But how? The function is anonymous. How can we call the stored procedure from an external system if it has no name?

When you create stored procedures in Cosmos DB, the names by which they are published and invoked isn’t expressed in JavaScript. Instead, the names are bits of metadata that can be described in JSON like this:

var procedureDef = {
  id: "SaveADocument",
  body: function(doc) {
    __.createDocument(__.getSelfLink(),
      doc,
      function (err, newDoc) {
        __.response.setBody(newDoc.id)
      });
  }
}

See the source code in the body while the name of the procedure is the id property. In other languages that don’t speak JSON natively, the body (the source code) will be expressed as a string whenever you create or update a stored procedure. Now, let’s use Visual Studio Code and a small Node.js application to deploy the stored procedure and invoke it.

You might want to use Python, Java or C# to interact with Cosmos DB instead. All those languages are at home in Visual Studio Code and all of them have first-class SDKs. Check out GotCosmos.com for some great samples and tutorials for working with Cosmos DB from those languages.

With both Code and Node installed on your Windows, Mac or Linux workstation, issue the following commands in a terminal window to create a new project directory, initialize it, and start the Code editor:

mkdir UpsertCosmosSP
cd UpsertCosmosSP
touch index.js config.js
npm init
npm install @azure/cosmos
code .

If you’re running Windows which has no touch command, try these two statements to create the empty index.js and config.js files instead:

type nul >> index.js
type nul >> config.js

In Code, add these exports to the config.js file:

exports.connection = {
    endpoint: 'https://localhost:8081',
    authKey: 'C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=='
};

exports.names = {
    database: 'DELETE_ME_SOON',
    collection: 'Playground',
};

This configuration assumes that you’re using the Cosmos DB Emulator running on port 8081 of the local machine and using the default master key. However, the emulator only runs on Windows 10 or Windows Server 2016 at the time of this writing.

If you want or need to use a real Cosmos DB account in the Azure cloud, you’ll have to replace the connection endpoint and authKey with your own. In that case, use the Cosmos DB blade in the Azure Portal to create a new account or locate an existing one where you have read-write access. From the account’s Keys page, fetch the read-write endpoint URI and the primary or secondary key, replacing the endpoint and authKey values in the config.js file.

You may also change the database name and the collection name in the configuration file if you like. If you leave them as shown, the application will automatically create a new database called DELETE_ME_SOON in your Cosmos DB account. In that new database, a collection named Playground will also be created as needed. That’s where the stored procedure will be deployed along with any documents you create during the test runs of the application below.

In the index.js file, add the following application code. The full source code for this example is also available on Github.

var CosmosClient = require('@azure/cosmos').CosmosClient;
var config = require('./config.js');
var client = new CosmosClient({
    endpoint: config.connection.endpoint,
    auth: { masterKey: config.connection.authKey }
});

async function upsertProcedureAndExecute(sprocDef, docToInsert) {
    const { database } = await client.databases
        .createIfNotExists({ id: config.names.database });
    const { container } = await database.containers
        .createIfNotExists({ id: config.names.collection });
    const { sproc } = await container.storedProcedures.upsert(sprocDef);
    const { body: results, headers } = await sproc.execute(docToInsert);
    if (headers && headers['x-ms-request-charge'])
        console.log(`Charge = ${headers['x-ms-request-charge']} RU`);
    if (results)
        console.log(`DocID = ${JSON.stringify(results)}`);
    // comment in the next line to delete the database
    // await database.delete();
}

var docToSave = {
    message: 'Hello Cosmos DB',
    timestamp: (new Date()).toISOString()
};

var procedureDef = {
    id: 'saveDocument',
    body: function (doc) {
        __.createDocument(__.getSelfLink(),
            doc,
            function (err, newDoc) {
                __.response.setBody(newDoc.id)
            });
    }
};

upsertProcedureAndExecute(procedureDef, docToSave)
    .catch((err) => { console.error(JSON.stringify(err)); });

Lines 1 – 6 load the configuration file and instantiate the Cosmos DB client. Lines 8  – 21 define the upsertProcedureAndExecute function which starts by creating the database named in the configuration file if it doesn’t already exist. Similarly, the collection will be created as necessary. Then the stored procedure is upserted to the collection. The term upsert in the context of deploying a stored procedure means that if the procedure doesn’t already exist by the provided id, it will be created. If it does exist, it will be overwritten with the source code you provide.

Lastly, the stored procedure is invoked with the document to be saved. The request charge (expressed in Cosmos DB Resource Units) will be fetched from a response header and logged to the console along with the unique ID assigned to the new document.

When I’m doing development in Cosmos DB, I find that it’s useful to watch the request charges. Knowing how expensive various operations are as you move along is a good way to stay connected to the performance of your database.

You can run the application from the command line by executing “node index.js” in a terminal window which should output something like this to the console:

Charge = 5.45 RU
DocID = "8c6ec318-ed0a-3c02-216b-bc5161bfc5ba"

You can also run the application in the Visual Studio Code debugger by pressing F5 or clicking Debug / Start Debugging from the menu. The Code debugger for Node.js is very rich, allowing you to set breakpoints, interactively inspect variables and the call stack, evaluate expressions and much more.

You’ve observed that if you save a document to a Cosmos DB collection without an id property, an id will be created for it, as a GUID in string form. However, while every document saved to a Cosmos DB collection must have a unique id, they aren’t required to be GUIDs or follow any other specific pattern for that matter. They only need to have unique values. Try saving a document with an id of your own by replacing the docToSave object in the sample app with something like this:

var docToSave = {
    message: 'Hello Cosmos DB',
    id: 'testing123',
    timestamp: (new Date()).toISOString()
};

The first time you save the document by invoking the SaveADocument stored procedure, it will work correctly because no document with the id ‘testing123’ already exists. However, if you run it again, you’ll get an exception saying something like:

TypeError: Unable to get property 'id' of undefined or null reference

The error message isn’t super helpful but it does indicate that there’s something wrong with the ‘id’ property. In this case, we’ve attempted to violate a uniqueness constraint within the collection during the second invocation of the  __.createDocument() method. If it’s your intent to allow callers to replace existing documents that way, simply change the stored procedure definition to call __.upsertDocument() instead of __.createDocument() like this:

var procedureDef = {
    id: 'saveDocument',
    body: function (doc) {
        __.upsertDocument(__.getSelfLink(),
            doc,
            function (err, newDoc) {
                __.response.setBody(newDoc.id)
            });
    }
};

Now you can call the stored procedure over and over with documents having the same id value without errors and watch the timestamps and other properties change each time you do so.

Before I finish this article, I need to address something I’ve been doing wrong from the beginning. As it turns out, things can go wrong when you use complex, networked computing systems. We need to account for the various error conditions that might occur. Moreover, as a multi-tenant database, Cosmos DB has a range of constraints that dictate how stored procedures must behave. Based on so-called bounded execution rules, Cosmos DB may decide that it cannot accept your request at the current time. If that happens, we should obey and convey that information back to the caller. Here’s an updated procedure definition that handles both the error and non-acceptance cases:

var procedureDef = {
    id: 'saveDocument',
    body: function (doc) {
        var accepted = __.upsertDocument(__.getSelfLink(),
            doc,
            function (err, newDoc) {
                if (err) throw err;
                __.response.setBody({ id: newDoc.id, completed: true })
            });
        if (!accepted) __.response.setBody({ completed: false });
    }
};

If you save this version of the stored procedure, you’ll see that a Boolean flag is returned in non-error cases that indicates whether or not the upsert operation was allowed to complete. Also, if errors occur, they’ll be thrown back to the server-side engine which will roll back the current transaction. Cosmos DB’s automatic rollback of transactions depends on our throwing exceptions when things don’t go as planned.

A gentle reminder: if you created a Cosmos DB collection in the cloud as part of this exercise, please be sure to delete it if you don’t want to incur any ongoing charges once you’ve completed the exercise.

In the next article in this series, we’ll round out our examination of the basic document-oriented functions in the Collection class like __.queryDocuments and __.deleteDocument. We’ll also dive into continuations, another key concept related to working nicely within Cosmos DB’s bounded execution rules.

I fell in love with JMESPath using the Azure CLI. Many of the Azure CLI commands support a –query parameter which can be used to filter and shape the output using JMESPath expressions. Adam Raffe has a good blog post on using JMESPath in the Azure CLI which you should read to learn more. But here’s a sample to illustrate how useful JMESPath is. Imagine that you want to list all the Redis Cache instances in a subscription. Maybe you start with this command:

$ az redis list

The output is large. Here’s the JSON for a single node:

[
  {
    "accessKeys": null,
    "enableNonSslPort": false,
    "hostName": "abc01.redis.cache.windows.net",
    "id": "/subscriptions/432a801f-3521-4752-9445-40610812027e/resourceGroups/ABC-WebApp/providers/Microsoft.Cache/Redis/abc01",
    "linkedServers": [],
    "location": "West US",
    "name": "abc01",
    "port": 6379,
    "provisioningState": "Succeeded",
    "redisConfiguration": {
      "maxclients": "256",
      "maxmemory-delta": "2",
      "maxmemory-reserved": "2"
    },
    "redisVersion": "3.2.7",
    "resourceGroup": "ABC-WebApp",
    "shardCount": null,
    "sku": {
      "capacity": 0,
      "family": "C",
      "name": "Basic"
    },
    "sslPort": 6380,
    "staticIp": null,
    "subnetId": null,
    "tags": {},
    "tenantSettings": null,
    "type": "Microsoft.Cache/Redis",
    "zones": null
  }
]

Imagine if you had many Redis Cache instances in your subscription. The output would be unwieldy. The chances are good that you don’t need all the information that’s returned. Perhaps you’re only interested in name of the server and the SSL port. And let’s suppose that you only want information on instances that have “abc” in the name. JMESPath to the rescue:

$ az redis list --query "[?contains(name,'abc')].{ server: hostName, port: sslPort }"

This query returns only those elements in the response that contain “abc” in the name. It then shapes the output to include only the hostName and sslPort, naming them server and port. The simplified output looks like this:

[
  {
    "port": 6380,
    "server": "abc01.redis.cache.windows.net"
  }
]

That’s both nice for reading and skinny on the wire. What if you could offer the callers of your Cosmos DB-based APIs the ability to filter and shape the output like this? If I were using the Cosmos DB Table API, OData and LINQ are available to accomplish that sort of thing. But with the SQL API, we’ll have to write a bit of code. Consider this simple Node.js function to fetch information about U.S. weather stations:

let documentClient = require('documentdb').DocumentClient;
let cosmos_uri = process.env["STATION_COSMOS_URI"];
let cosmos_key = process.env["STATION_COSMOS_READONLY_KEY"];
let databaseId = process.env["STATION_COSMOS_DATABASE_NAME"];
let collectionId = process.env["STATION_COSMOS_COLLECTION_NAME"];
let client = new documentClient(cosmos_uri, { 'masterKey': cosmos_key });
let collectionLink = "/dbs/" + databaseId + "/colls/" + collectionId + "/";

module.exports = function (context, req) {
  let filterQuery = `SELECT * FROM c WHERE c.State = "${req.params.state}"`;
  try {
    let queryIterator = client.queryDocuments(collectionLink, filterQuery);
    queryIterator.toArray(function (err, matchingDocuments) {
      if (err) {
        context.done(err);
        return;
      }
      context.done(null, { status: 200, body: matchingDocuments, headers: { 'Content-Type': 'application/json' }});
    });
  } catch (ex) {
    context.done(ex);
  }
};

The function requires that you pass the U.S. state to limit the results. Let’s fetch the weather stations in the state of Virginia:

https://weatherapi.azurewebsites.net/api/StationQuery/state/VA

This operation returns information about several dozen weather stations in Virginia. It’s a long list but here’s the first one to show you how the records are shaped:

[
    {
        "WBAN": "00120",
        "WMO": null,
        "CallSign": "JFZ",
        "ClimateDivisionCode": null,
        "ClimateDivisionStateCode": 44,
        "ClimateDivisionStationCode": null,
        "Name": "CLAYPOOL HILL",
        "State": "VA",
        "Location": "TAZEWELL COUNTY AIRPORT",
        "Latitude": 37.067,
        "Longitude": -81.8,
        "GroundHeight": 2651,
        "StationHeight": 0,
        "Barometer": 0,
        "TimeZone": -5,
        "id": "655785f7-92d5-74cb-c1db-52df225a2ee5"
    }
]

Now suppose we want to query only for the stations below 20 feet of ground elevation. Of course, we could modify the Node.js function to accept extra predicates, attaching them to the WHERE clause. With Cosmos DB, that’s a pretty safe thing to do since there are no INSERT, UPDATE, DELETE, ALTER and DROP statements in the language that could be injected to do harm. In fact, appending the U.S. state to the SELECT statement as shown above is quite safe in Cosmos DB. If a hacker tried to inject something malicious through the URL, at best they’d get back junk. More likely than not, the query would just fail since there’s no way to modify the data or the configuration of a Cosmos DB with a classic SQL injection attack.

In considering whether or not to allow API users to add new SQL predicates, we must ask ourselves:

1. Why make our API users learn how to construct SQL predicates?
2. What if we want to change the implementation from SQL API to something else?

Having an abstraction like OData or JMESPath that sits atop the API for filtering and projection makes a lot of sense. Using JMESPath, here’s the URL we’d like to be able to send to fetch all the weather stations in Virginia below 20 feet of ground elevation:

https://weatherapi.azurewebsites.net/api/StationQuery/state/VA?query=[?GroundHeight < `20`]

It’s surprisingly easy to add this functionality to the Node.js function. After importing JMESPath, check for the new query parameter in the iterator and execute it as a JMESPath search:

if (req.query && req.query.query) {
  try {
    matchingDocuments = jmespath.search(matchingDocuments, req.query.query);
  }
  catch (ex) {
    context.done(ex);
    return;
  }
}

Here’s the full source code of the updated function on GitHub. With that change in place, the URL that restricts the results to those weather stations below 20 feet of elevation now returns only six stations in Virginia, not dozens of them. However, we’re not quite done. Imagine that we want to trim down the JSON response to include only the location and the geographic coordinates of the matching records. Let’s try this URL and see how JMESPath handles it:

https://weatherapi.azurewebsites.net/api/StationQuery/state/VA?query=[?GroundHeight < `20`].{ description: Location, geo: { latitude: Latitude, longitude: Longitude } }

Here’s the much smaller output:

[
    {
        "description": "LANGLEY AFB AIRPORT",
        "geo": {
            "latitude": 37.0828,
            "longitude": -76.3603
        }
    },
    {
        "description": "RONALD REAGAN WASHINGTON NATL AP",
        "geo": {
            "latitude": 38.8472,
            "longitude": -77.0345
        }
    },
    {
        "description": "NORFOLK NAS",
        "geo": {
            "latitude": 36.9375,
            "longitude": -76.2893
        }
    },
    {
        "description": "NAVAL AUXILIARY LANDING FIELD",
        "geo": {
            "latitude": 36.695,
            "longitude": -76.1356
        }
    },
    {
        "description": "QUANTICO MCAF",
        "geo": {
            "latitude": 38.5036,
            "longitude": -77.305
        }
    },
    {
        "description": "FELKER ARMY AIRFIELD",
        "geo": {
            "latitude": 37.1333,
            "longitude": -76.6
        }
    }
]

Excellent. I’ll leave you with a few tips. First of all, executing an extra filtering type operation on result sets that have already been reduced with server-side query predicates can be wasteful. For this article, I deliberately chose to layer JMESPath functionality on top of a U.S. state-based weather station API because I know that the result sets from the original query will always be very small. Each U.S. state has a few dozen official weather stations, most of them positioned at medium- to large-sized airports or government buildings. Even California, which has the largest number of weather stations among all the states, has only about 100 of them. Querying for a few dozen records and filtering some of them out with JMESPath isn’t terribly wasteful in the grand scheme of things.

However, if your API is going to query against larger result sets or if the volume of activity on your filtering API is high enough, you should consider attaching the user’s predicates and/or their output-shaping projections onto the original database queries for efficiency. In parting, I’ll leave you with the Cosmos DB query that implements the filtering and projection from the example above:

SELECT VALUE { description: c.Location, geo: { latitude: c.Latitude, longitude: c.Longitude } } FROM c WHERE c.State = "VA" AND c.GroundHeight < 20

This produces an output that’s identical to our JMESPath powered API. If this query expression were passed through to Cosmos DB, we wouldn’t need JMESPath at all. But your application (or your users) would need to understand SQL syntax. And you would have some difficulty moving away from SQL-based queries in the future if you wanted to do so. Food for thought, as we say.

var crypto = require("crypto");  

function getAuthorizationTokenUsingMasterKey(verb, resourceType, resourceId, date, masterKey) {  
    var key = new Buffer(masterKey, "base64");  
    var text = (verb || "").toLowerCase() + "\n" +   
               (resourceType || "").toLowerCase() + "\n" +   
               (resourceId || "") + "\n" +   
               date.toLowerCase() + "\n" +   
               "" + "\n";  
    var body = new Buffer(text, "utf8");  
    var signature = crypto.createHmac("sha256", key).update(body).digest("base64");  
    var MasterToken = "master";  
    var TokenVersion = "1.0";  
    return encodeURIComponent("type=" + MasterToken + "&ver=" + TokenVersion + "&sig=" + signature);  
}

That’s nice. However, what if I want to generate a Cosmos DB auth token in a Postman pre-request script? The built-in Node.js crypto module isn’t available in Postman but CryptoJS is. This version of the script which does a few encodings the CryptoJS way should do the trick:

var now = new Date().toUTCString();
pm.environment.set("utcDate", now);

var verb = 'GET';
var resourceType = pm.variables.get("resourceType");
var resourceId = pm.variables.get("resourceId");

var text = (verb || "").toLowerCase() + "\n" + (resourceType || "").toLowerCase() + "\n" + (resourceId || "") + "\n" + now.toLowerCase() + "\n" + "" + "\n";
var key = CryptoJS.enc.Base64.parse(pm.variables.get("masterKey"));
var signature = CryptoJS.HmacSHA256(text, key).toString(CryptoJS.enc.Base64);

var MasterToken = "master";
var TokenVersion = "1.0";
var authToken = encodeURIComponent("type=" + MasterToken + "&ver=" + TokenVersion + "&sig=" + signature);

pm.environment.set("authToken", authToken);

For the script to work, you’ll need to define a few variables in a Postman environment file:

• utcDate – this will be set by the script. It’s used in the calculation of the auth token and will also be placed into an HTTP header named x-ms-date.
• masterKey – don’t be stupid. Production secrets shouldn’t be stored in a Postman environment file. Copy the primary or secondary master key from your Cosmos DB account into this variable. If you’re only performing GET operations, you should be able to use a read-only key here.
• authToken – this will be computed by the script and placed into the Authorization HTTP header.
• resourceId – the path to the object(s) you want to reference. For example, I have a database named Finance with a collection named Investors. The resourceId would be set to “dbs/Finance/colls/Investors” in that case.
• resourceType – the type of resource you wish to access. If I’m after documents, I’ll save “docs” here. See the Cosmos DB documentation for other resource types such as “dbs” or “colls”.

One value I was not able to fetch from the Postman Sandbox was the HTTP method of the current request. Unfortunately I hard-coded that in the script to “GET” for now. If you know how to obtain that value using the Sandbox API, let me know and I’ll update this article.

As the Cosmos DB documentation explains, there are a few required headers when making calls through Cosmos DB’s REST API. It’s worth mentioning a few of them here:

• x-ms-date – the UTC date that’s also used in the computation of the auth token. Since the pre-request script captures this and places it in the environment file, that same variable can (and should be) used to send this header.
• x-ms-version – the latest version of the Cosmos DB REST API is 2017-02-22 so I hard-coded that. See the Cosmos DB documentation for other versions and the features they introduced.
• Authorization – set by the execution of the pre-request script. Interestingly, Cosmos DB Authorization headers have no scheme named in them which is something of a no-no per the HTTP specification.

Now, set the address for Postman to fetch to:

https://<<account>>.documents.azure.com/{{resourceId}}/{{resourceType}}

Where <<account>> is your Cosmos DB account name and {{resourceId}} and {{resouceType}} are resolved from the environment file as described above. When you send the request, you should get back the objects you’ve requested. If you’ve requested a lot of documents with your query, you may get an HTTP response header called x-ms-continuation as described here which would require you to use the continuation pattern to get more results.

The server has not found anything matching the Request-URI.

However, if you think APIs are like web pages, you might be perplexed by such an interpretation. Maybe 404 feels like an error because it connotes that something went wrong with the web app. Oh no, the page wasn’t found! The world is coming to an end! Run for the hills! Save the women and children!

But APIs aren’t web apps, are they? They aren’t pages at all. APIs are cacheable, uniformly-addressable, resource-oriented interfaces. Given the address for a resource, if it’s not available, the API should return the HTTP 404 status in most cases.

Unfortunately, there’s so much momentum around the idea of 404 being an error condition that it’s really hard to get developers to think differently about how the web is supposed to work. Monitoring tools, log indexers and server health checks don’t help much for changing minds. So many of these tools dutifully treat 404 as an error condition that well-meaning API developers can’t see outside of the little boxes into which they’ve been coaxed.

One of the most troubling manifestations of this page-oriented bias is Microsoft Azure’s App Service server health check. Deploying a pure Web API to an Azure App Service, you’ll find that you’re subject to all sorts of page-specific constructs related to health. Most notably, if you return HTTP 404 from a server too often, the health checks will mark the instance as failing. Obviously, if pages are missing, something’s clearly wrong with that one naughty instance out of ten. The sheer narrow-mindedness of that idea just boggles my mind given that all the servers run the same code and connect to the same resources by definition.

If this incorrect behavior meant that Azure simply recycled instances more often than it needed to, that wouldn’t be too high a price to pay for their pedantic interpretation of the HTTP specification. Unfortunately, we don’t stop paying the price there. The standard load balancer for Azure App Service seems to be completely perplexed when specific server instances are marked as unhealthy. Performance degrades quickly as more and more instances are quarantined and taken out of rotation while new ones have to be created and spun up. What a mess!

If you’re using a managed API gateway like Azure API Management (APIM), there’s a fairly elegant way to deal with this particular problem. Have your API return 200-series statuses for these conditions, keeping the health checks ignorant and happy, then translate the outbound HTTP statuses to the ones you really want to convey at the edge. Here’s some outbound policy you can add to your API to pick up a special response header named RealHttpStatus and return that instead.

<outbound>
  <set-variable name="realHttpStatus" value="@(Convert.ToInt32(context.Response.Headers.GetValueOrDefault("RealHttpStatus", "0")))" />
  <set-header name="RealHttpStatus" exists-action="delete" />
  <base />
  <choose>
    <when condition="@(context.Variables.GetValueOrDefault<int>("realHttpStatus") == 404)">
      <set-status code="@(context.Variables.GetValueOrDefault<int>("realHttpStatus"))" reason="Not Found" />
    </when>
    <otherwise></otherwise>
  </choose>
</outbound>

The policy begins by fetching the special response header called RealHttpStatus if it exists. The API should inject this header whenever it means to return something that might be misinterpreted or mishandled by the application server’s management tools. Next, the policy removes the special header so clients won’t see how our chicanery was perpetrated. Lastly, if the integer value of the special header is 404, the actual status returned by APIM will be 404, regardless of what the back end actually provided via the actual HTTP status code.

Of course, this policy’s <choose> element can be extended to include as many other interesting HTTP status types as you might require. Your API can go on respecting HTTP for all its beauty and prescience while keeping those fossilized ne’er-do-wells completely in the dark about your villainous plans.

using System;   
using System.Net;
using System.Text;   
using System.Globalization;   
using System.Security.Cryptography;

public static HttpResponseMessage Run(HttpRequestMessage req, TraceWriter log)
{
    string id = Environment.GetEnvironmentVariable("APIM_SAS_ID", EnvironmentVariableTarget.Process);
    string key = Environment.GetEnvironmentVariable("APIM_SAS_KEY", EnvironmentVariableTarget.Process);
    DateTime then = DateTime.UtcNow.AddMinutes(10);
    // seconds must be zero for this to work
    DateTime expiry = new DateTime(then.Year, then.Month, then.Day, then.Hour, then.Minute, 0, DateTimeKind.Utc);
    using (HMACSHA512 hmac = new HMACSHA512(Encoding.UTF8.GetBytes(key)))
    {
        string dataToSign = id + "\n" + expiry.ToString("O", CultureInfo.InvariantCulture);
        byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
        string signature = Convert.ToBase64String(hash);
        return req.CreateResponse(HttpStatusCode.OK, new {
            SharedAccessSignature = $"{id}&{expiry:yyyyMMddHHmm}&{signature}"
        });
    }
}

This Azure Function requires two web application settings named APIM_SAS_ID and APIM_SAS_KEY to be used in the hashing process. You can fetch those from the APIM publisher portal (and wherever they may be on the main Azure portal once APIM is fully integrated there). The token that gets generated from this code will be good for ten minutes. You can add more time if you like by modifying the line of code that calls DateTime.AddMinutes(). Currently, APIM SAS tokens can be generated to last up to thirty days although it’s not good practice to make them last that long.

The problem that I found with the snippet of code that was shown in the APIM documentation is that the inclusion of the seconds in the expiration time caused it to fail validation no matter how the middle (EX) portion of the SAS token was formulated. Perhaps I was doing something else wrong but I found that by setting the seconds to zero in the expiration date, I was able to generate SAS tokens that are honored by the APIM REST API. Here’s a GET operation that fetches the value of a property in APIM named SOME_APIM_PROP using the SharedAccessSignature Authorization schema:

GET /properties/?$filter=name eq 'SOME_APIM_PROP'&api-version=2016-10-10 HTTP/1.1
Host: apimftw.management.azure-api.net
Authorization: SharedAccessSignature 57d83b84fe7a801&201703281726&1Zvq5h...
Cache-Control: no-cache

With this Azure Function in place (and the credentials to access it), I can generate SAS tokens for APIM any time I like using a simple, clean HTTP interface. Azure Functions are great architectural building blocks for any modern, API-centric design. If you agree or disagree with that assertion, let me know by reaching me on Twitter @KevinHazzard. Enjoy.

<validate-jwt
    header-name="Authorization"
    failed-validation-httpcode="401"
    require-scheme="Bearer">
  <openid-config url="https://login.windows.net/contoso.onmicrosoft.com/.well-known/openid-configuration" />
  <audiences>  
    <audience>80123615-1afd-48b7-b897-77273a479532</audience>
  </audiences>
  <issuers>
    <issuer>https://sts.windows.net/ca4870f4-8639-4c87-ac58-7d7678dd33b6/</issuer>
  </issuers>
  <required-claims>
    <claim name="appid" match="all">
      <value>3689a0f2-4bb0-419d-a384-62e1e4a9c6d8</value>
    </claim>
  </required-claims>
</validate-jwt>

That’s nice. A little bit of markup and all that nasty security plumbing is handled outside the API. But what if we want to pass some individual claims named inside the token on to the API backend? Unfortunately, Azure APIM doesn’t have that built into JWT token validation policy. Ideally, we’d be able to extract claims during validation into variables and pass them in HTTP headers before the request is forwarded to the backing API. Until that feature is added, here’s how you can do that:

<set-header name="token-app-id" exists-action="override">
  <value>@{
  string appId = "NOAUTH";
  string authHeader = context.Request.Headers.GetValueOrDefault("Authorization", "");
  if (authHeader?.Length > 0)
  {
    string[] authHeaderParts = authHeader.Split(' ');
    if (authHeaderParts?.Length == 2 && authHeaderParts[0].Equals("Bearer", StringComparison.InvariantCultureIgnoreCase))
    {
      Jwt jwt;
      if (authHeaderParts[1].TryParseJwt(out jwt))
      {
        appId = jwt.Claims.GetValueOrDefault("appid", "NOAPPID");
      }
    }
    return appId;
}</value>
</set-header>

In this code, I’ve added some script inside the <set-header> policy statement to fetch the Authorization header from the request, check that it’s a Bearer type token, attempt to parse it (which checks the token’s signature), then finally extracts the value of one specific claim. Most of that work already happens inside <validate-jwt> policy, as you can imagine. Until there’s an easier way to extract JWT claims individually, the solution shown here works nicely. Enjoy.

If you agree with me that this feature should be built right into the <validate-jwt> policy, please upvote the feature request I wrote on the APIM feedback site.

When you’re trying to master something new, doing the Simplest Possible Thing (SPT) to demonstrate it working is often the best way to learn. It’s so easy when you’re applying new concepts to get wrapped up in the mechanics and muck of the tools and frameworks you’re using. For example, trying to add a new database interface to an existing web site can be frustrating if the machinery of the web engine makes it hard to tell what’s going wrong with your initial tests. SPT reminds us that integrating the new framework into a big application might not the best way to really understand it.

SPT directs us to first create a small test application where we can integrate the database libraries without the cruft and ceremony of the larger web application. We can typically bake some clean, clear, consistent debug outputs into the test application in a matter of minutes. Very quickly, the Simplest Possible Thing shows how to do the integration into the larger application.

And SPT isn’t just for students. I create test applications so often that several times per year, I’ll go through my projects folder and delete hundreds of tiny test projects that begin with the phrase Kill_{some specific test name}_{date of creation}. I started using that naming pattern for my SPT tests many years ago because I had created hundreds of them that ended up cluttering up my projects folder. With this consistent naming pattern in place, I can quickly go back to find specific pre-integration test that I did recently. Embedding the date in the project name also helps me to know which ones I can clean up. If they’re more than a few months old, they’re probably safe to discard.

The next time you are coaching someone who seems to be struggling with integrating a new idea into a larger application, I hope you’ll instruct them to do the Simplest Possible Thing to prove or disprove that they’ve got it right. Oftentimes, I’m surprised by what SPT teaches me. And I’m a salty, old dog who loves to learn new tricks.

Get the Source Code

Get the Slides

If you are a user group leader and would like me to deliver this presentation to your group, contact me on Twitter as KevinHazzard. Enjoy!

Over the past 3.5 decades, I’ve made four major shifts in my career. When I started out, I wrote code in assembly language and C language. If you don’t know what those are, no worries. Just suffice it to say that they are super low-level abstractions and close to the actual hardware. I was really good at understanding the machine architecture and using it to my advantage. I even claimed that for a few minutes in 1984, I knew everything there was to know about the PC. Since then, I’ve been slipping. That’s true of everyone in this field though. There is no person who can know everything about all the complex systems that make up the modern PC and the Internet. I know a lot more than the average developer given my background that reaches all the way back to those low-level language days. But truth be known, I rarely use that old knowledge about electrical engineering and processor architecture to get work done today.

The first major shift in my career, which I’ll call v2.0, happened in the mid-1980s. The out-of-date mainframe pre-compiler I used during the metamorphosis was called C with Classes but the language had already been renamed C++. The idea of object-orientation was dazzlingly cool to me. Being able to hide data inside of objects that expose safe access methods was liberating and empowering. I became a real expert in object-oriented design and in the use of the C++ Standard Template Library, riding that wave for more than a decade to create some very cool software.

Career v3.0 for me came in the late 1990s when Java appeared on the scene. This highly expressive but simpler derivative of C++ promised to make our code safer and portable from one processor architecture to another. I was working with a group within the Intel Architecture Lab (IAL) that was implementing a high-performance Java Virtual Machine for the Intel processors. My team was creating all sorts of system-level software in Java that was going to change everything about the PC ecosystem, we believed. Then, one day, high-level folks from Microsoft visited our campus in Hillsboro, Oregon and spent all day in conferences with our IAL managers. Within days, all of the Java projects in IAL, including the screamingly fast new Java compiler and virtual machine were shut down. It was a real tragedy that changed the history of the PC forever. I left Intel and spent the next few years doing all sorts of interesting Java work that I enjoyed.

In 2001 while teaching C++ at a local college, a student asked what I thought of C# (pronounced C Sharp for those who don’t know). I had no idea what it was so I called a friend in IAL and he explained that the reason Microsoft had abandoned Java (and ostensibly got its partner Intel to do the same) was to make way for a new language that would compete with Java. I was intrigued so he put me in touch with someone at Microsoft who sent me a gold CD-R with “Cool” scrawled on it in red Sharpie ink. (Cool was the project code name for C#.) I popped the CD in a drive, ran the installer and started playing. In the matter of minutes, I could tell that C# was different from Java in some interesting ways. Over the next hour, I fell in love with it. Thus began v4.0 of my career. I dove head first into C# and into Microsoft’s .NET ecosystem. I was probably one of the first college professors to teach C# in the world, filling my first classroom with .NET fledglings in 2002. By 2008, I had become a Microsoft C# Most Valuable Professional (MVP) and stayed in the award program for the next seven years.

At the height of my experience as an MVP, I started work on a very large scale database project. Every software developer works with data but this project was really huge, at least one hundred times the size of any data project I’d worked on to date. I discovered that my skills as a programmer were massively inadequate to operate in that environment. The big problem was that my programming brain was wired to be iterative and imperative. I had spent 20 years telling computers what to do. The problem with really big data is that it’s often so big and so unwieldy that you just can’t tell it what to do. Instead, you must work with languages that allow you to describe what you want done instead of how it must be done. This is called the declarative programming model which is essentially the opposite of the imperative (command-based) programming I’d been doing for a couple of decades.

For the first time, I really needed to use declarative, set-based languages like Transact Structured Query Language (T-SQL) to get my work done. There was really no other way to pull it off in C# (or any other language I knew at the time). My mind was transformed through the process. I could never see the world in the same ways again. My job, which had always been to virtualize the world through silicon, became a search for patterns instead. There were scores of data patterns to be discovered. Code patterns emerged at every turn when I started looking for them. I became a pattern junkie in v5.0 of my career. I even wrote a book with my friend Jason Bock called Metaprogramming .NET which focuses on techniques for generating code based on patterns to make software fault tolerant and adaptive to change.

Version 6.0 of my career starts tomorrow. As I write this, I am sitting in a hotel room in Las Vegas, Nevada waiting for the start of Amazon.com’s 2015 AWS re:Invent conference. I am convinced that most companies will shift their infrastructures to the cloud in the next few years. And I’m sure that the way Amazon AWS products are structured, they will capture and keep the majority of cloud market for the next decade.

The reasons for my beliefs about the success of AWS are complex but it boils down to this. AWS is all about micro-architecture at any scale. That may sound like gibberish to those who haven’t built an enterprise system but it’s demonstrably true that all successful, complex systems are built from small parts working in concert to create value. AWS has generally designed their products in this way, deliberately or otherwise. Each product is a kind of gear that can connected to the others to create really interesting new things. There are serious integration challenges remaining but the AWS products fit together quite well, in general. Moreover, they scale dynamically so there’s appeal to small companies and large ones, alike.

We’re already seeing the leading edge of the conversion as small- and medium-sized companies are testing the waters of cloud computing in large numbers to gain some operational advantages over their larger competitors. In the next five years, the motivation for moving to the cloud will shift from operational, financial and tactical to strategic. Services will become available in the cloud that we could never even imagine in our racks of single-purpose servers sitting in private data centers. Machine learning will give way to what’s next: predictive analytics that permeates all of our data, all of our code naturally and automatically whether it’s shaped and purposed for that or not. Those companies trying to compete by running single-purpose, monolithic software will simply fall behind.

In reality, I started the shift to v6.0 of my career a while back. I’ve been using Microsoft Azure and Amazon AWS for a couple of years for my clients. But I’ve been using these services in the old-school way. When AWS Lambda was released a few months ago, that’s when the light bulb in my mind really lit up brightly. AWS Lambda is the simplest idea. What if you could write functions that could be instantiated in microseconds to get any sort of generic work done? And what if the system could scale out the number of available machines for running those functions heuristically and automatically?

Lastly, what if that system of scalable functions could be triggered from anywhere? Saving a file might run a function. That code might write to a database which invokes other functions. Et cetera. Suddenly, I saw a way to compose complex, scalable systems with simple, interconnected building blocks. Moreover, this is all done without owning a single server in the classical sense. In 34 years, I’ve come full circle from wanting to master everything about the machines I use to not wanting any machines at all. Version 6.0 of my career will be just as exciting as v1.0 was to me. For that, I’m truly grateful to be in this profession.

Let me finish by saying that although I think Amazon AWS will dominate in this space, Microsoft and Google will also do quite well. I’m not ignoring them. But the elegance, simplicity and highly composable nature of Amazon’s AWS products will make them a great choice for my clients. Viva Las Vegas!

The Technical Enthusiast

Someone who wears mock turtlenecks and probably like shiny things. They listen to ColdPlay (a lot) and think it’s pure joy to make the lights blink at home by pressing buttons on the $5,000 Macbook Pro that they leave at the office every day at 4:30pm. They do no real work per se but they smell great and clients love the exotic coffees they bring to the office. Favorite board game: Euphoria, Build a Better Dystopia.

The Geek

Whether using a Mac or a PC,  they spend time at the terminal prompt getting stuff done. They wear shorts and flip flops to work because anything else takes too much maintenance and prep time. Besides, so-called “work” happens at 3 am many days because flashes of genius ain’t gonna be tamed by the clock, you know. Geeks make clients happy because they are often perfectionists who take pride in their work and have a modicum of social skills. They sport facial hair when the chromosomes allow for it and play Cards Against Humanity in their spare time. Geeks love a good India Pale Ale.

The Nerd

Pretty much geeks with fewer social skills who are typically obsessive about one thing, e.g. making sure everyone understands why Batman is superior to Superman in every conceivable way. Whatever machines these folks are on, it’s definitely running Linux. They play Battlestar Gallactica for days on end, typically until the participants start needing medical attention. These folks get work done but it’s on their own terms. Probably best to stock up on Jolt Cola and slide pizzas under the door once in a while praying that they meet deadlines. Favorite beverage: kombucha served fresh at the Renaissance Faire.

The Dweeb

These are nerds with zero social skills and who alienate any potential clients based on the way they smell alone. They don’t bathe often because it takes time out of their MMORPG binges. They usually live in their Mom’s basement and suffer from vitamin D deficiency which leads to their peculiarly large foreheads (in both men and women alike). They might be brilliant but since nobody ever speaks to them outside of the context of BBS software they haunt to discuss rebuilds of various UNIX kernels, no one knows for sure. We’re also not sure if these folks eat or drink in the classical sense but the video of Richard Stallman eating something from his foot during a recent FSF conference is an important clue to their means of sustenance.