Need to add a folder to a document library in SharePoint 2013 using REST - SharePoint Hosted app

Question

I'm trying to add a folder to a document library using REST in a SharePoint 2013 SharePoint hosted app. It is hosted in an Office 365 developer site. I'm following the guidelines in MSDN here as well as using the excellent samples on dev.office.com (especially the REST Helper).

While capturing the request during debugging I can't see any problems with my request compared to the documentation and samples. I haven't had issues with any GET requests either.

Here is my request:

var datatext = "{'__metadata': {'type': 'SP.Folder'}, 'ServerRelativeUrl': '" + serverRelativeUrl + foldername + "'}";

$.ajax({
    url : $appweburl + "/_api/web/folders",
    type: "POST",
    data: datatext,
    headers: {
        "accept": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(),
        "content-type": "application/json;odata=verbose",
        "content-length": datatext.length
    },
    success: function (data) {
        success(data);
    },
    error: function (data) {
        failure(data);
    }
});

This generates an error "value does not fall within the expected range"

So this uses "data" instead of "body" because "body" was always generating a JSON Reader error. All of the samples indicate "body" but I found other sources that show this key should be "data" in a POST like this, and it resolves the JSON reader error. I ensure that ServerRelativeUrl leads with a "/" as well as filename.

Any help is greatly appreciated.

EDIT: To follow up on this, I was successful using JSOM only. It turns out that you must add a ListItem to the list and specify the content type to be a folder to achieve this. It works, but it makes me wonder if you have to do something similar in REST - that is rather than use the folder endpoints, do it like adding a listitem to a list. I have not confirmed it.

Answer 1

Usually the error Value does not fall within the expected range occurs since ServerRelativeUrl property was specified in incorrect format.

The following formats are supported:

• [Document Library]/[New Folder] list/library relative url
• /[Site]/[Web]/[Document Library]/[New Folder] - site collection relative url
• http(s)://[Server]/[Site]/[Web]/[Document Library]/[New Folder]
  absolute url

How to create a Folder using SharePoint 2013 REST

Assume the following site structure:

`News` site (under `sites` managed path)
   |
   `Documents` library
       |
      `Archive` folder

Then the following examples demonstrate how to create a folder named 2010 in Documents library:

Example 1

createFolder(_spPageContextInfo.webAbsoluteUrl,'/sites/news/Documents/Archive/2011')
.done(function(data)
{
    var folder = data.d;
    console.log('Folder ' + folder.Name  + ' has been created successfully');
})
.fail(
function(error){
    console.log(JSON.stringify(error));
});

Example 2

createFolder(_spPageContextInfo.webAbsoluteUrl,'Documents/Archive/2010')
.done(function(data)
{
    var folder = data.d;
    console.log('Folder ' + folder.Name  + ' has been created successfully');
})
.fail(
function(error){
    console.log(JSON.stringify(error));
});

where

function executeRequest(url,method,headers,payload) 
{
    if (typeof headers == 'undefined' || headers == null){
        headers = {};
    }
    headers["Accept"] = "application/json;odata=verbose";
    if(method == "POST") {
        headers["X-RequestDigest"] = $("#__REQUESTDIGEST").val();
    }   

    var ajaxOptions = 
    {       
       url: url,   
       type: method,  
       contentType: "application/json;odata=verbose",
       headers: headers
    };
    if(method == "POST") {
      ajaxOptions.data = JSON.stringify(payload);
    }  

    return $.ajax(ajaxOptions);
}

function createFolder(webUrl,folderUrl) 
{    
    var url = webUrl + "/_api/web/folders";   
    var folderPayload = { '__metadata': { 'type': 'SP.Folder' }, 'ServerRelativeUrl': folderUrl}; 
    return executeRequest(url,'POST',null,folderPayload);
}