Provisioning and Adding Your Data

After you've registered an account for SDS, your first task will be to provision your data source and start adding data. Suppose that you are hired to create a data hub for Coho Winery, a prestigious wine merchant. The hub will include listings for red wines, white wines, and Champagnes, and will also include video clips of taste tests and reviews. The following diagram illustrates how you might map this to the ACE model.

Figure 2. Example data structure for Coho Winery

As you can see, we will create a single authority with an ID of Coho. We will add a container named Wines, which we will use for heterogeneous storage of RedWine, WhiteWine, and SparklingWine entities. We will add a second container named Media to store taste tests and reviews as BLOBs.

Now that you've established your data structure, your first development task will be to create the authority.

Creating Authorities

As discussed earlier, an authority is the top layer in the SDS data model. Every authority has a DNS name assigned to it, which effectively makes the authority a unit of geographical location. Because of this, every authority ID must be globally unique.

To create an authority using the REST interface, you first create an XML payload that describes your authority:

<s:Authority xmlns:s='http://schemas.microsoft.com/sitka/2008/03/'>
<s:Id>coho</s:Id>
</s:Authority>

The Id property is compulsory, and can only contain lowercase letters, numbers, or dashes. In case you're wondering, "Sitka" is the pre-release codename for SDS.

Remember that to create an authority, you must scope your operation at the service level. As such, your next step is to send an HTTP request to the service:

https://data.beta.mssds.com/v1/

Because you are performing a create operation, you use the HTTP POST method to stream your XML payload to the service as a byte array. Set the Content-Type header to application/x-SDS+xml, and set the Content-Length header to the length of your XML payload in bytes. The following C# code sample illustrates this process. This assumes that you have defined a string named myPayload that contains your XML payload, and a string named serviceUri that contains the URI of the service as provided in the previous paragraph.

HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(serviceUri);
//Set the request headers
request.Credentials = new NetworkCredential(myUserName, myPassword);
request.Method = "POST";
UTF8Encoding encoding = new UTF8Encoding();
request.ContentLength = encoding.GetByteCount(myPayload);
request.ContentType = "application/x-ssds+xml";
//Write the XML payload to the request stream
using (Stream myStream = request.GetRequestStream())
{
myStream.Write(encoding.GetBytes(myPayload),
encoding.GetByteCount(myPayload));
}

When the operation has completed, SDS will send an HTTP response. The response includes an HTTP status code that indicates whether or not your operation was successful (a status code of 201 indicates that a resource was created).

Note: For full end-to-end code examples in C#, Java, and Ruby, together with SOAP examples in C#, visit the SDS Primer site on MSDN.

Creating Containers

You can use containers to store homogeneous data (entities of the same kind) or heterogeneous data (entities of different kinds). If you use a container to store homogeneous data, the container is analogous to an individual database table. If you use a container to store heterogeneous data, the container is analogous to an entire database. Whereas a traditional database uses tables and schemas to organize data, containers impose no such restraints. Instead of tables and schemas, you use entity metadata to structure your data storage and retrieval. We'll cover this in more detail when we discuss entities.

Going back to the Coho Winery example, our next step is to create containers to store wine listings and media files. Because containers do not require schemas, the creation process is exactly the same for both containers: you don't need to create columns or specify what type of entity the container will hold.

You can create a container in a very similar way to how you create an authority. First, you assemble an XML payload that describes your container:

<s:Container xmlns:s='http://schemas.microsoft.com/sitka/2008/03/'>
<s:Id>Wines</s:Id>
</s:Container>

To create a container, you must scope your operation at the authority level. To do this, you address your HTTP request to the authority URI:

https://coho.data.beta.mssds.com/v1/

Creating Entities

When you work with flexible entities (in other words, non-BLOB entities), you need to be aware of two different types of properties. Flexible properties are defined by the user and stored in a simple string object dictionary. You can add as many or as few flexible properties to each entity as you want. Currently, you can define property values in String, Base64Binary, Boolean, Decimal, and DateTime data types.

Metadata properties are fixed properties that provide information on the entity itself. Each entity (with the exception of BLOB entities, which we'll cover later) has three metadata properties.

Table 3: Entity metadata properties

<RedWine xmlns:s='http://schemas.microsoft.com/sitka/2008/03/'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:x='http://www.w3.org/2001/XMLSchema' >
<s:Id>CohoSauvignon05</s:Id>
<vineyard xsi:type='x:string'>Coho Vineyard</vineyard>
<vintage xsi:type='x:string'>2005</vintage>
<grape xsi:type='x:string'>Cabernet Sauvignon</grape>
<region xsi:type='x:string'>New Zealand</region>
<description xsi:type='x:string'>Full-bodied and fruity</description>
<thumbnail xsi:type='x:base64Binary'>/9j/4AAQSkZJ… </thumbnail>
<price xsi:type='x:decimal'>16.95</price>
</RedWine>

HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(containerUri);
request.Method = "POST";
request.ContentLength = 1234567;
request.ContentType = "video/x-msvideo";
request.Headers["Content-Disposition"] =
"attachment; filename='Coho1.avi'";
request.AllowWriteStreamBuffering = false; //enable full streaming
request.Headers["Slug"] = "CohoSauvignon05TastingNotes";

Remember, for full end-to-end code examples you can visit the SDS Primer site on MSDN at http://msdn.microsoft.com/en-us/library/cc512417.aspx.