cURL'ing up with SQL Server Data Services

  • Article

We've begun working with some external customers (and a considerable number of internal ones) on the project and one of the first requests that came up was regarding the use of cURL. 

cURL, as many of you already know, is a pretty cool command line utility which can be used to issue HTTP requests.  However we haven't, until this point, documented exactly how you can use the service from cURL.  This post will address that.

Enumerating your Authority

In this example I'll illustrate how you can query an authority for all of the containers that are located within it.  Before we get to this however I'll explain a bit more about how cURL functions. 

cURL uses various command line parameters to construct the HTTP request on your behalf.  As you might guess the -X parameter is used to specify the verb (HTTP method) that you wish to use on the request.  The -u parameter is used to specify the credentials to use and finally the last parameter is the URL you want to use. 

Command line syntax to query the authority:

curl -X GET -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/?q=''

Output

<s:EntitySet xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSc
hema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
  <s:Container>
    <s:Id>testcontainer</s:Id>
    <s:Version>1</s:Version>
  </s:Container>
  <s:Container>
    <s:Id>testcontainer2</s:Id>
    <s:Version>1</s:Version>
  </s:Container>
</s:EntitySet>

Creating Containers and Entities

As I've mentioned previously here we use the POST verb to create entities within SSDS.  Now, because specifying the entire payload for a POST could be cumbersome cURL allows you to specify the filename where the payload can be found.  This done use the, "--data" parameter and the, "@" symbol.

We'll begin with creating a container with cURL.  We'll start by creating a simple file called, "CurlContainer" containing the following XML payload:

<s:Container xmlns:s="https://schemas.microsoft.com/sitka/2008/03/">
    <s:Id>CurlContainer</s:Id>
</s:Container>

Now that this is complete we can construct the command line syntax that we'll need to send the request to the service.

Command line syntax to create the container:

curl -X POST --data @CurlContainer -H "Content-Type: application/xml"  -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/

A couple of things that you might notice here that are different from our prior syntax.  The first is that the verb has changed (that's pretty obvious).  The second item is that we've used the, "--data" parameter to specify the payload.  We didn't need to use that before since we were only querying the service. 

Finally, and perhaps most importantly, is that we specify the content type of data in the request.  This is done using the, "-H" parameter along with the header data.  If this isn't specified then the request will be denied with a 400 so do remember to use it.

Now, when we query the authority as we did earlier I get the following output returned to me.

<s:EntitySet xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
  <s:Container>
<s:Id>CurlContainer</s:Id>
<s:Version>1</s:Version>
</s:Container>
  <s:Container>
    <s:Id>testcontainer</s:Id>
    <s:Version>1</s:Version>
  </s:Container>
  <s:Container>
    <s:Id>testcontainer2</s:Id>
    <s:Version>1</s:Version>
  </s:Container>
</s:EntitySet>

Switching to entity creation we find that not a lot has changed.  The only meaningful difference is the URL that we provide and the payload content.  Following the steps just described I can create a new entity, "CurlEntity" within the CurlContainer I just created.  Listed below is the payload I've created as well as the syntax used to create the entity.

Payload

<CurlEntity xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
    <s:Id>CurlEntity</s:Id>
    <Name xsi:type="x:string">Jeff Currier</Name>
</CurlEntity>

Command line syntax to create the entity:

curl -X POST -H "Content-Type: application/xml" --data @CurlEntity.xml -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/CurlContainer

Finally, let's just query the container to see my new data.

Command line syntax to query the container:

curl -G -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/CurlContainer?q=''

Output

<s:EntitySet xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSc
hema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
  <CurlEntity>
    <s:Id>CurlEntity</s:Id>
    <s:Version>1</s:Version>
    <Name xsi:type="x:string">Jeff Currier</Name>
  </CurlEntity>
</s:EntitySet>

Updating Entities

Now that we can create and query things we need to have a way of updating them otherwise things just aren't that interesting.  We do this, as always in a RESTful service, using the PUT verb.  In this case I'm going to change the, "Name" property on my newly created entity to another name. 

Like we did previously we'll create a file which will contain the payload definition for the request.  I've created this file, "CurlEntity2.xml" and will provide this on the command line.  Listed below is both the payload as well as the command line syntax for updating.

Update Payload:

<CurlEntity xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
    <s:Id>CurlEntity</s:Id>
    <Name xsi:type="x:string">Jason Hunter</Name>
</CurlEntity>

Command line syntax for updating an entity:

curl -X PUT --data @CurlEntity2.xml -H "Content-Type: application/xml" -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/CurlContainer/CurlEntity

Output from listing the contents of the container

<s:EntitySet xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSc
hema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema">
  <CurlEntity>
    <s:Id>CurlEntity</s:Id>
    <s:Version>2</s:Version>
    <Name xsi:type="x:string">Jason Hunter</Name>
  </CurlEntity>
</s:EntitySet>

Deleteing Entities

All things must come to an end even when it comes to entities.  We do this in RESTful services using the Delete verb.  Notice here that there is no need to specify a payload or a content-type header.  None of this is required as the service will determine what to delete based upon the URL. 

Command line syntax:

curl -X DELETE -u "<userid>:<password>" https://<authority-id>.data.beta.mssds.com/v1/CurlContainer/CurlEntity

Output from listing the contents of our container:

<s:EntitySet xmlns:s="https://schemas.microsoft.com/sitka/2008/03/" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:x="https://www.w3.org/2001/XMLSchema"/>

That wraps up our cURL example for this evening.  If there are other languages or tools that you would be interested in seeing examples in please do let us know!

--Jeff--