We have just released version 1.2 of our REST API. In this version you can finally use the following HTTP Verbs; GET, POST, PUT and DELETE. This will enable you to read, create update and delete SharePoint resources. I will show you how you can create Webs, Lists, List Items, Fields and ContentTypes using the same uniform interface.
In this post I will start by showing you how to create, update and delete a Web. Before you can follow this example you have to download the latest version of the Bamboo REST API here. Run the installer and activate the feature on your main Web Application. After you have done this open your favorite web browser and browse to a site collection hosted in the Web Application where you activated the feature. My URI looks like this http://server/mashpoint/1/.
|
 |
If you read the introductory post on our REST API you know this is the XHTML representation of the root web.
We want to create a sub-web of this root web. And to do this we will POST to the Webs collection.
If you hover your mouse over the hyperlink you will see the URI to this collection.
In my example it is http://jndtvbx64/mashpoint/1/Webs.
|
 |
(The reason I like the XHTML representation so much is that it can be discovered by using your favorite web browser.)
One way to POST to the Webs collection is to create an HTML form like this:
|
<html>
<body>
<form method="POST" action="http://jndtvbx64/mashpoint/1/Webs" >
<input type="text" name="Title" value="SubWeb" />
<input type="text" name="Description" value="A sub web created from MashPoint REST API" />
<input type="text" name="Url" value="subweb"/>
<input type="text" name="Lcid" value="1033"/>
<input type="text" name="WebTemplate" value="Blog"/>
<input type="text" name="UseUniquePermissions" value="true"/>
<input type="text" name="ConvertIfThere" value="false"/>
<input type="submit" name="Create" value="Create"/>
</form>
</body>
</html>
|
As you can see the method is set to POST and the action URI is the Webs collection. All the form fields corresponds to the properties of the Web. You can set as many properties as you want but at the minimum you have to supply the Url.
|
 |
If you open this form in a web browser and click Create you will create a new Web.
|
 |
We can check that it is a BLOG with the correct Title and Description. Now let's take a closer look at what is sent back from the server when you create a new resource. I use fiddler to inspect Http Traffic, if you don't have it you can download it here. Go back to the HTML form and post the form again. You should get an HTTP Error 409.
|
 |
The reason for this is that the Url is already in use. Go back and modify the Url and repost the form. You can use the inspectors tab to take a closer look at the request and the response.
|
 |
Let's take a look at the response to our POST. The status code returned is 201 Created and the important Location Header is set to the URI of the newly created resource (in this case SPWeb). This is true whenever you create a new resource be it a Web List or List Item.
|
 |
So let's click on this link in fiddler to open the newly created web in our web browser.
|
 |
Now we are going to delete this web. A web browser can't issue the DELETE verb but using Fiddler we can construct this request. To delete a resource we use DELETE on the URI. Select the Request Builder tab and paste in the URI. Select DELETE as the verb and finally click Execute. (If you get a 401 error just refresh your browser with some page to update the authentication headers)
|
 |
If you get status 200 back the web should be deleted. To verify this change the Verb from DELETE to GET in Fiddler and Execute the request. You should get status 404 back (Not found).
|
I wanted to show you using a web browser and fiddler so you understand how many clients can interact with the REST API. If you write a .NET client that will interact with the REST API I suggest that you use the WebClient class. Let's take a look at some C# code that will create and delete a web.
|
public void CanCreateAndDeleteWeb()
{
WebClient wc = new WebClient();
wc.Credentials = CredentialCache.DefaultCredentials;
NameValueCollection values = new NameValueCollection();
values["Title"] = "Web created from REST API";
values["Description"] = "A web created from REST";
values["Url"] = "subweb";
values["Lcid"] = "1033";
values["WebTemplate"] = Microsoft.SharePoint.SPWebTemplate.WebTemplate.Blog.ToString();
values["UseUniquePermissions"] = false.ToString();
values["ConvertIfThere"] = false.ToString();
wc.UploadValues("http://jndtvbx64/mashpoint/1/Webs", "POST", values);
// Read the Location Header so we can delete the newly created web
string newuri = wc.ResponseHeaders.Get("Location");
wc.UploadValues(newuri, "DELETE", values);
}
|
In the next post we will manage Lists in our newly created web.
|