Fr

Microsoft has created DocumentDB, a schema-free

database offering fast access, the exibility of a NoSQL
database, and the ability to scale, as it is offered from
the Azure platform.
Learning DocumentDB adopts a practical, step-by-step
approach to help you learn the basics of DocumentDB
and use your newfound abilities in real-life scenarios and
enterprise solutions. We start with the absolute basics,
such as setting up a DocumentDB environment, and
guide you through managing your databases and
executing simple and complex queries. Next, we explain
how to work with DocumentDB using the open REST
protocol and demonstrate how JavaScript works with
DocumentDB. You'll then learn how to authenticate
and execute queries. Moving on, you'll nd out how to
use DocumentDB from within Node.js to kick-start your
Node.js projects. Next, you'll discover how to increase
the performance of your DocumentDB database and
ne-tune it. Finally, you'll get to grips with using
DocumentDB in conjunction with other services offered
by the Microsoft Azure platform.

Who this book is written for

Create, manage, and congure your

DocumentDB environment
Execute SQL queries, from simple to
complex and nested ones, against
your database

Fine-tune your DocumentDB database to

optimize performance and costs

professional expertise distilled

pl
e

P r o f e s s i o n a l

Interact with DocumentDB using different

technologies and platforms
Build a real-life scenario using C# and put
DocumentDB at the heart of Azure solutions
Understand how to migrate from your current
datastore to DocumentDB

$ 34.99 US
22.99 UK

P U B L I S H I N G

Sa

Get to know about advanced DocumentDB

techniques such as scopes, portioning,
indexing, triggers, UDFs, and security

Riccardo Becker

This book is for novice developers and database

architects who need a thorough knowledge of the features
of DocumentDB and how to develop applications with it.
Basic knowledge of SQL would be helpful.

What you will learn from this book

Learning Azure DocumentDB

Learning Azure
DocumentDB

ee

E x p e r t i s e

D i s t i l l e d

Learning Azure
DocumentDB
Create outstanding enterprise solutions around DocumentDB
using the latest technologies and programming tools with Azure

Prices do not include

local sales tax or VAT
where applicable

Visit www.PacktPub.com for books, eBooks,

code, downloads, and PacktLib.

Riccardo Becker

professional expertise distilled

P U B L I S H I N G

In this package, you will find:

The author biography

A preview chapter from the book, Chapter 5 'Using REST to Access
Your Database'
A synopsis of the books content
More information on Learning Azure DocumentDB

About the Author

Riccardo Becker works full time as a principal IT architect for CGI in the

Netherlands. He holds several certifications and his background in computing goes

way back to 1998, when he started working with good old Visual Basic 5.0 (or was it
6.0?). Ever since, he has fulfilled several roles, such as a developer, lead developer,
architect, project leader, practice manager. Recently, he decided to accept the role of
a principal IT architect where he focuses on innovation, cutting-edge technology,
and specifically on Microsoft Azure, the Internet of Things, and cloud computing
in general.
In 2007, he joined the Microsoft LEAP program where he got a peek at the move
Microsoft was about to make on their road to the cloud. Pat Helland gave him that
insight, and since the first release of Microsoft Azure on PDC 2008, he started to
focus on it, keeping track of the progress and the maturity of the platform. In the past
few years, he has also done a lot of work on incubation with his employer, raising
awareness of cloud computing in general and Microsoft Azure in particular.

Preface
In August 2014, Microsoft announced the preview of their DocumentDB service
offering. DocumentDB is a NoSQL database that meets the requirements of today's
applications that evolve at a higher pace, including modifications to the data model.
DocumentDB covers all this by offering a schema-free document database that
offers flexibility, scalability, automated indexing, and a mature range of querying
possibilities. Recently, Microsoft announced support for geospatial indexing and
querying, opening a whole new range of possibilities.
Setting an example, Microsoft utilizes DocumentDB in its renewed
http://www.msn.com, servicing 450 million unique monthly visitors.
25 percent of these visitors have their own personalized data and this data
is services from DocumentDB.
DocumentDB greatly enhances the flexibility of your evolving applications and offers
a rich querying environment for any kind of data that you store.
This book covers all the concepts and possibilities of DocumentDB by covering the
theory with lots of examples in every chapter. This book is linear and every chapter
builds on the knowledge of the last. For the more experienced users, chapters can
also be read individually and in any order.
By the end of this book, you will be able to use DocumentDB in your own daily work
and benefit from best practices.

What this book covers

Chapter 1, Getting Started with DocumentDB, covers the basics of DocumentDB.
It explores the data model and compares DocumentDB with other NoSQL
technologies. It also outlines the pricing model of DocumentDB. By the end of
this chapter, we will learn how to set up a DocumentDB environment and how
to prepare Visual Studio 2015 to start building solutions using DocumentDB.
[v]

Preface

Chapter 2, Setting up and Managing Your Database, provides detailed information

on how to set up, maintain, and manage your DocumentDB. It also covers how
to monitor your DocumentDB and, based on monitoring results, reconfigure
DocumentDB.
Chapter 3, Basic Querying, provides an insight into the basic querying options for
DocumentDB. It covers how to create, update, read, and delete documents from
your DocumentDB in the most basic form.
Chapter 4, Advanced Querying, provides an insight into all the possibilities in the SQL
grammar that is available for DocumentDB.
Chapter 5, Using REST to Access Your Database, discusses how to use DocumentDB
using the open REST protocol. It also covers how to use JavaScript to work with
DocumentDB and how to authenticate and execute queries.
Chapter 6, Using Node.js to Access Your Database, provides a detailed description of
how to use DocumentDB features with Node.js
Chapter 7, Advanced Techniques, covers indexes and how to use them effectively.
It also covers how to measure the performance of our database and use
partitioning techniques.
Chapter 8, Putting Your Database at the Heart of Azure Solutions, describes patterns
that can be applied to your Azure solution, collaborating with DocumentDB. It also
covers some patterns and how to integrate DocumentDB inside your current Azure
solution by replacing some of the current data repositories, which will be moved
to DocumentDB.

Using REST to Access

Your Database
In this chapter, we will discuss how to operate against DocumentDB using the
open REST protocol. There are different APIs and SDKs available for DocumentDB,
such as .NET, Java, Python, Node.js, and JavaScript. For all other programming
environments and platforms, there is the possibility to use the REST interface.
In this chapter, we will cover:

The basics of the REST protocol

How to use the REST API against DocumentDB

Writing some C# code to support our demos

Using the Fiddler tool to demonstrate the usage of the REST API

The Fiddler tool is free to download from http://www.telerik.com/fiddler.

Understanding the basics of REST

Representational State Transfer (REST) is a software architecture for building web
services. REST communicates over HTTP using the HTTP verbs GET, POST, PUT,
and DELETE. REST operations involve resources and the HTTP verbs indicate what
actions to perform. The following sections describe the HTTP verbs in combination
with REST and demonstrate some typical operations. The four above-mentioned
verbs are sufficient to perform all the CRUD operations we need in modern systems.

[ 63 ]

Using REST to Access Your Database

Check out the following table to see the differences between the verbs and
some examples:
Verb
POST
GET

PUT

DELETE

Operation

Happy flow

Unhappy flow

Creates a
resource

POST/devices
201 created

404 not found or 409 conflict

when item already exists

Gets a resource

GET/devices

GET/devices/{id}

Returns a list of all

devices

Returns a specific device or 404

not found if the device does
not exist

Updates a
resource

PUT/devices

PUT/devices/{id}

Potentially updates the

complete collections of
devices

Updates the specific device or

returns a 404 not found if the
device does not exist.

Deletes a
resource

DELETE/devices

DELETE/devices/{id}

Deletes the complete

collection of devices.
For data safety reasons,
this operation should be
carefully implemented.

Returns a 200 if successful or a

404 not found if the device ID
cannot be found in the devices
collection

A web service can be labeled as RESTful if it conforms to several constraints

described in the following table:
Constraint

Description

Client-server

This involves a strict separation of concerns. Clients are not concerned

about persisting data, which is the full responsibility of the server. On
the other hand, servers are not concerned about the calling party or
what technology is used on the client side. Since servers are not strictly
bound to their clients, REST servers can be simple and very scalable
(since there is no state). The most important aspect in this constraint is
that the interface between clients and servers remains the same, while
the underlying technology can change at any time.

Stateless

The server maintains no state between different requests. Every single

request from a client should contain all the information that is needed to
be able to properly service the request. The server can persist the state,
for example, in a database (or a DocumentDB collection).

[ 64 ]

Chapter 5

Constraint

Description

Cacheable

Server responses can be cacheable if applicable. This is most appropriate

for the GET request, since caching a POST request on the client does
not really make sense. Proper caching can eliminate the traffic between
clients and the server which increases performance.

Uniform
interface

An important aspect of REST is the uniform interface that simplifies and

decouples the REST architecture. This allows systems to change and
evolve independently.

Using the GET verb

The HTTP GET method is used to retrieve a resource or a list of resources. The GET
verb returns XML or JSON format data and a HTTP response 200 (OK). When the
GET fails for some reason it returns response codes in the 400 range like 404 NOT
FOUND or 400 Bad Request.
As the GET verb implies, it should be used only for reading data and not
manipulating it. Although it is possible to build REST services using the GET
verb to modify data, it is bad practice.
The GET verb is idempotent since it does not change the data.

Using the POST verb

The POST verb is intended to be used for creating a new resource. If the POST is
successful, it should return the HTTP status 201.
The POST verb is not idempotent, since calling the POST method multiple times will
result in multiple resources being created (unless the underlying business logic
prevents this).

Using the PUT verb

The PUT verb should be used to update resources. A PUT request contains a body
with the new state of a resource (not only updated fields example) that replaces the
original resource.
A successful PUT request returns a 200. Sometimes, PUT can be used to create
resources (instead of POST) if the client is responsible for choosing a unique identifier.
In this case, the PUT request contains a unique identifier that does not exist on the
server side yet. This practice is possible, though not very common, and should be
used carefully. The PUT verb is idempotent, since changing the state of a resource
multiple times with the same message body only changes the original resource once.
[ 65 ]

Using REST to Access Your Database

Using the DELETE verb

The DELETE verb is used to delete a resource or a range of resources.
The DELETE verb is idempotent, since deleting a resource multiple times does not
affect the state. The resource is gone and remains deleted. It is good practice to return
a 404 when you try to delete a resource multiple times, since the resource does not
exist anymore.

Querying DocumentDB resources

This section covers how to use REST to query DocumentDB resources.
Each resource has a corresponding URI. The database account is managed
by the Azure Management API and the base URI for a DocumentDB is
https://management.azure.com/subscriptions/{subscriptionid}/
resourcegroups/{resourcegroupname}/providers/Microsoft.DocumentDB/
databaseAccounts/{accountname}.

The subscriptionid is the Azure subscription that is the owner of

the database

The resourcegroupname is the resource group that the account is under

The accountname is the database account name

The base URI for the rest of the resources are based on the URI endpoint that is
specifically created for the database account name. The following table shows the
base URI for each type of resource:
Resources
Database
User
Permission
Collection
Stored
procedure

Base URI
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/users/{_rid-user}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/users/{_rid-user}/permissions/{_rid-perm}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}/sprocs/{_rid-sproc}

[ 66 ]

Chapter 5

Resources
Trigger
UDF
Document
Attachment

Base URI
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}/triggers/{_rid-trigger}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}/udfs/{_rid-udf}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}/docs/{_rid-doc}
https://{databaseaccount}.documents.azure.com/dbs/{_riddb}/colls/{_rid-coll}/docs/{_rid-doc/attachments/{_ridattch}

Setting request headers

In order to be able to perform query operations against DocumentDB, the following
headers need to be set:
Standard header

Description

Authorization

The authentication type and signature token. This is required.

Only the master key token is allowed for this operation.

Content-Type

This is optional. Must be set to application/query+json.

This table can be found at https://msdn.microsoft.com/en-us/library/

dn783363.aspx.
The Content-Type does not seem to be required, although it
is specified in any case.

Generating the authorization header

Before we can use REST to operate against our DocumentDB, we need to generate
the right authorization header for every request. The following C# snippets are used
to do so:
/// <summary>
/// This method creates a signature based on masterkey,
resourceId (if any), resourcetype
/// verb (default = GET) and dates (if any)
/// </summary>
/// <param name="masterKey">MasterKey of DocumentDB
database</param>

[ 67 ]

Using REST to Access Your Database

/// <param name="resourceId">_rid of the resource involved (if
any)</param>
/// <param name="resourceType">docs or colls etc.</param>
/// <param name="verb">GET, POST etc.</param>
/// <returns></returns>
public static string GetSignature(string masterKey, string
resourceId, string resourceType, string verb = "GET")
{
const string AuthorizationFormat = "type={0}&ver={1}&sig={2}";
const string MasterToken = "master";
const string TokenVersion = "1.0";
//always use datetime.UtcNow
var xDate = DateTime.UtcNow.ToString("r");
var
var
var
var

masterKeyBytes = Convert.FromBase64String(masterKey);
hmacSha256 = new HMACSHA256(masterKeyBytes);
resourceIdInput = resourceId ?? string.Empty;
resourceTypeInput = resourceType ?? string.Empty;

var payLoad = string.Format(CultureInfo.InvariantCulture,

"{0}\n{1}\n{2}\n{3}\n{4}\n",
verb.ToLowerInvariant(),
resourceTypeInput.ToLowerInvariant(),
resourceIdInput.ToLowerInvariant(),
(xDate ?? string.Empty).ToLowerInvariant(),
String.Empty);
//compute the hash of this payload
var hashPayLoad = hmacSha256.ComputeHash(
Encoding.UTF8.GetBytes(payLoad));
//generate token
var authorizationToken = Convert.ToBase64String(hashPayLoad);
//encode and return the token
return System.Web.HttpUtility.UrlEncode(string.Format(
CultureInfo.InvariantCulture,
AuthorizationFormat,
MasterToken,
TokenVersion,
authorizationToken));
}

Depending on the verb (GET, POST, and so on), the resourceType (dbs, colls, or
docs), the resourceId (optional), and the master key that can be found in the Azure
portal, the authorization key is generated.

[ 68 ]

Chapter 5

Getting all databases

In order to get a list of all the databases inside a collection, we use the following
C# snippet:
client.DefaultRequestHeaders.Add("x-ms-date", DateTime.UtcNow.
ToString("r"));
client.DefaultRequestHeaders.Add("x-ms-version", "2015-08-06");
//get signature based on masterkey and the resourcetype dbs (no
resourceId involved yet).
signature = GetSignature(masterKey, "", "dbs", "GET");
client.DefaultRequestHeaders.Add("authorization", signature);
string getResponse = client.GetStringAsync(new Uri(baseUri,
"dbs")).Result;

Using Fiddler to enter the raw REST input, we get the following result:

The output of this REST call is shown in the following screenshot:

Adding a document
The following snippets show how to create a document in a certain collection:
//get signature based on masterkey, collection resource id and
resource type documents (docs)
signature = GetSignature(masterKey, collectionRid, "docs", "POST");
client.DefaultRequestHeaders.Remove("authorization");

[ 69 ]

Using REST to Access Your Database

client.DefaultRequestHeaders.Add("authorization", signature);
string json = JsonConvert.SerializeObject(new
{
id = Guid.NewGuid().ToString(),
test = "hello DocumentDB, created via REST API!"
});
HttpContent contentPost = new StringContent(json);
//add payload to body
//do the post against the REST API and create the document
var postResponse = client.PostAsync(new Uri(baseUri,
string.Format("dbs/{0}/colls/{1}/docs",
deviceHubDb.ResourceId, collectionRid)),
contentPost).Result;
Console.WriteLine(postResponse.ReasonPhrase);

This time, we need to use the POST verb (which affects the authorization key as well).
The payload of the PostAsync call is a JSON file and the final status code is created.
Again, the REST representation of this operation in Fiddler is shown in the
following screenshot:

Now that we have seen how to use the GET and POST verb against the REST API of
DocumentDB, we can execute all operations needed in an enterprise scenario for
platforms that do not have a DocumentDB SDK available.
The source projects also demonstrate how to get the right collection (similar to listing
all databases) by providing a resource ID representing the designated database.
[ 70 ]

Chapter 5

Summary
In this chapter, we covered the very basics of the REST protocol and what verbs are
available in the protocol. We saw that every single resource inside our DocumentDB
can be referenced by a unique URI. This URI is the basis for executing REST-based
queries against our databases, collections, documents, and all other available
resources. We wrote some C# code in order to generate the authorization key that
is needed for every REST request. Finally, we fired some REST queries against our
DocumentDB to get a list of all the databases and how to create a document inside
a collection. We used C# and we saw the raw HTTP representations of the same
queries inside Fiddler.
In the next chapter, you will learn how to use Node.js to perform a subset of the
activities from this chapter. The focus will be on how to use DocumentDB from
Node.js to kick-start your Node.js projects.

[ 71 ]

Get more information Learning Azure DocumentDB

Where to buy this book

You can buy Learning Azure DocumentDB from the Packt Publishing website.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet
book retailers.
Click here for ordering and shipping details.

www.PacktPub.com

Stay Connected: