SharePoint REST API and Lists with Folders : A Redux

Published on Author Rob Windsor3 Comments

Last July I wrote a blog post on the PAIT Group blog entitled SharePoint REST API and Lists with Folders. I wrote the post because the REST API has incomplete support for folders in lists and a lot of people were having problems trying to figure out how to perform common tasks. The two main culprits were creating new folders and adding items into a folder.

I was recently going over some forum questions and I saw one on creating list items in a folder. One of the answers to the post mentioned using the SharePoint 2010 REST API to solve the problem. This hadn’t occurred to me previously but it turns out that using the SharePoint 2010 REST API makes the tasks of folder creation and adding items to a folder easy peasy.

Update (June 20, 2018):

I’m updating the post based on Marc’s comment below. It turns out there was an update to the REST API documentation on how to add a list item to folder. This part of the documentation was not there when I last checked nor was it there when I wrote my original blog post. That fact aside, following the new documentation will enable you to properly add a list item to a folder if you are using SharePoint Online. My tests show that the code shown in the documentation does not work in SharePoint 2013 or SharePoint 2016. If you are using those versions of SharePoint you will still need to use the SharePoint 2010 REST API.

Adding a Folder

In the code below I’m adding a Folder named Folder 99 to the root folder of a list named FolderTest. The ContentTypeID property of the message body indicates that I want to create a folder and the Path property of the message body identifies the parent folder by its server relative URL.

function addFolderButtonClick() {
    var call = jQuery.ajax({
        url: _spPageContextInfo.webAbsoluteUrl + 
            "/_vti_bin/ListData.svc/FolderTest",
        type: "POST",
        data: JSON.stringify({
            ContentTypeID: "0x0120",
            Title: "Folder 99",
            Path: _spPageContextInfo.webServerRelativeUrl + "/Lists/FolderTest"
        }),
        dataType: "json",
        headers: {
            Accept: "application/json",
            "Content-Type": "application/json"
        }
    });
    call.done(function (data, textStatus, jqXHR) {
        var message = container.find("#message");
        message.text("Folder 99 added");
    });
    call.fail(function (jqXHR, textStatus, errorThrown) {
        failHandler(jqXHR, textStatus, errorThrown, 
            this.type, this.url, this.data);
    });
}

Adding an Item to a Folder Using the SharePoint 2010 REST API

This code was included when I first wrote this post. This technique will work with SharePoint 2010 and later. While this technique will work with SharePoint Online, I suggest you use the technique shown below if that is the version of SharePoint you are targeting.

In the code below I’m adding an item to the folder named Folder 99 in the list named FolderTest. It’s the Path property of the message body that identifies the target folder by its server relative URL.

function addItemButtonClick() {
    var call = jQuery.ajax({
        url: _spPageContextInfo.webAbsoluteUrl + 
            "/_vti_bin/ListData.svc/FolderTest",
        type: "POST",
        data: JSON.stringify({
            Title: "Item Z",
            Number: 40,
            Path: _spPageContextInfo.webServerRelativeUrl + 
                "/Lists/FolderTest/Folder 99"
        }),
        dataType: "json",
        headers: {
            Accept: "application/json",
            "Content-Type": "application/json"
        }
    });
    call.done(function (data, textStatus, jqXHR) {
        var message = container.find("#message");
        message.text("Item Z added to Folder 99");
    });
    call.fail(function (jqXHR, textStatus, errorThrown) {
        failHandler(jqXHR, textStatus, errorThrown, 
            this.type, this.url, this.data);
    });
}

Adding an Item to a Folder Using the SharePoint 2013 and later REST API

This update is based on Marc’s comment below. Please note that my testing indicates that this technique will only work with SharePoint Online. It will not work with SharePoint 2013 or 2016.

This example uses the somewhat obscure AddValidateUpdateItemUsingPath method which is a cousin of the ValidateUpdateListItem method. Generally I’ve seen these methods used to update a list item or document without adding a new version of the item or document. However in this case we are using the method to add a new item.

In the code below I’m adding an item to the folder named Folder 99 in the list named FolderTest. The FolderPath.DecodedUrl property of the body contains the server relative URL to the target folder. The form values property is an array of objects which each have two properties, FieldName and FieldValue. The sytax is a little bit odd but it gets the job done. Finally, setting the bNewDocumentUpdate property to false indicates that we want to add a new item rather than updating an existing item.

function addItemButtonClick() {
    var call = jQuery.ajax({
        url: _spPageContextInfo.webAbsoluteUrl +
            "/_api/Web/Lists/GetByTitle('FolderTest')/" +
            "AddValidateUpdateItemUsingPath",
        type: "POST",
        data: JSON.stringify({
            "listItemCreateInfo": {
                "FolderPath": {
                    "DecodedUrl":
                        _spPageContextInfo.webServerRelativeUrl +
                            "/Lists/FolderTest/Folder 99"
                },
                "UnderlyingObjectType": 0
            },
            "formValues": [
                {
                    "FieldName": "Title",
                    "FieldValue": "Item X"
                },
                {
                    "FieldName": "Number",
                    "FieldValue": "100"
                }
            ],
            "bNewDocumentUpdate": false
        }),
        dataType: "json",
        headers: {
            Accept: "application/json;odata=nometadata",
            "Content-Type": "application/json;odata=nometadata",
            "X-RequestDigest": jQuery("#__REQUESTDIGEST").val()
        }
    });
    call.done(function (data, textStatus, jqXHR) {
        var message = container.find("#message");
        message.text("Item X added to Folder 99");
    });
    call.fail(function (jqXHR, textStatus, errorThrown) {
        failHandler(jqXHR, textStatus, errorThrown, 
            this.type, this.url, this.data)
    });
}

Summary

It’s encouraging to see that Microsoft has addressed one of the two major issues related to working with folders in the REST API. Hopefully they will also address the folder creation issue soon. In the mean time you can use the SharePoint 2010 REST API as I describe above or you can use the Client Object Model which has had full support for folders since it was introduced with SharePoint 2010.

3 Responses to SharePoint REST API and Lists with Folders : A Redux

  1. Rob:

    This article shows how to work with folders and content therein in lists using REST:
    https://docs.microsoft.com/en-us/sharepoint/dev/sp-add-ins/working-with-lists-and-list-items-with-rest

    In other words, no need to revert to the SharePoint 2010 “REST” endpoint (in quotes because it doesn’t really conform to the standards). The above article needs some work, IMO, but since I haven’t had time to offer improvements, I’m not complaining too loudly.

    M.

    • Argh! I should have checked the documentation again before I wrote this post.

      The code to add a list item item to a folder wasn’t there when I last checked. I tried it out and it worked as advertised. I’ll update the blog post accordingly.

      That said, the code to create a new folder is the same as the last time I checked and it has the same issue that I describe in original blog post. The code creates the folder but it does not create the associated list item. Because of this the folder does not show in list views.

  2. I checked the same page as well and it was not there, I checked the web archive and it was not there as you mentioned. Thanks for the update.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.