SharePoint List REST API. Part 2

SharePoint List REST API

Second part of series about SharePoint REST API and CRUD operations. In this post I'll show how to perform operations with the following field types: Hyperlink, Metadata and DateTime.

Hyperlink

Hyperlink field value is an object not just a string. This object contains two properties: Url and Description.

Create


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val() // <-- digest
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "HyperlinkField": {// <-- hyperlink object
            "Description": "My blog",
            "Url": "http://blog.vitalyzhukov.ru"
        }
    })
});

Response with status 201 contains information about created item:


<?xml version="1.0" encoding="utf-8"?>
<entry>
    <category term="SP.Data.CRUDListListItem" />
    <content type="application/xml">
        <m:properties>
            <d:Id m:type="Edm.Int32">10</d:Id>
            <d:HyperlinkField m:type="SP.FieldUrlValue">
                <d:Description>My blog</d:Description>
                <d:Url>http://blog.vitalyzhukov.ru</d:Url>
            </d:HyperlinkField>
        </m:properties>
    </content>
</entry>

Read

To retrieve field value we need to specify its internal name in GET-requests:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(10)?$select=HyperlinkField", // <-- list item id
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

Update

We can not update only Description or only Url property. Entire object with both properties must be presented in update request:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(10)",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(), // <-- digest
        "X-HTTP-Method": "MERGE", // <-- for update request
        "IF-MATCH": "*" // <-- for update request
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "HyperlinkField": {// <-- hyperlink object
            "Url": "http://blog.vitalyzhukov.ru",
            "Description": "Sharepoint blog"
        }
    })
});

Delete

As we know from my previous post to delete some property we have to set it to null:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(10)",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(), // <-- digest
        "X-HTTP-Method": "MERGE", // <-- for update request
        "IF-MATCH": "*" // <-- for update request
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "HyperlinkField": null // <-- clear field value
    })
});



DateTime

CRUD operations with DateTime field is a very similar to text field ones. There are DateTime object instead of string values.

Create


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val() // <-- digest
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "DateField": new Date(2020, 0, 1)// <-- 1/1/2020 
    })
});

Read

To retrieve field value we need to specify its internal name in GET-requests:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(11)?$select=DateField", // <-- list item id
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

Response contains field value in UTC:


<?xml version="1.0" encoding="utf-8"?>
<entry>
    <content type="application/xml">
        <m:properties>
            <!-- UTC-3 TimeZone -->
            <d:DateField m:type="Edm.DateTime">2019-12-31T21:00:00Z</d:DateField>
        </m:properties>
    </content>
</entry>

Update

For updating date field no need convert date value to UTC. Server will do that itself before saving value into database.


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(10)",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(), // <-- digest
        "X-HTTP-Method": "MERGE", // <-- for update request
        "IF-MATCH": "*" // <-- for update request
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "DateField": new Date() // <-- current date
    })
});

Delete

See delete section for hyperlink field.



Single Metadata (Taxonomy)

Metadata field must be presented by SP.Taxonomy.TaxonomyFieldValue object.

Create


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val() // <-- digest
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "SingleTerm": {
            "__metadata": {
                "type": "SP.Taxonomy.TaxonomyFieldValue"
            },
            "TermGuid": "d3ce8903-4b4e-442e-8f19-161bf45be9e8", // <-- Term Id 
            "WssId": "-1" // <-- always "-1" 
        }
    })
});

Read

Read taxonomy field value via REST:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(11)?$select=SingleTerm", // <-- list item id
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

The response contains following data:


<entry>
    <content type="application/xml">
        <m:properties>
            <d:SingleTerm m:type="SP.Taxonomy.TaxonomyFieldValue">
                <d:Label>67</d:Label>
                <d:TermGuid>d3ce8903-4b4e-442e-8f19-161bf45be9e8</d:TermGuid>
                <d:WssId m:type="Edm.Int32">67</d:WssId>
            </d:SingleTerm>
        </m:properties>
    </content>
</entry>

As you can see SharePoint returns Id instead of label.

Update

As for create operation all we need is Term Id:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(11)",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(), // <-- digest
        "X-HTTP-Method": "MERGE", // <-- for update request
        "IF-MATCH": "*" // <-- for update request
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "SingleTerm": {
            "__metadata": {
                "type": "SP.Taxonomy.TaxonomyFieldValue"
            },
            "TermGuid": "33899e31-576e-4254-a9cf-d53bac59935a", // <-- Term Id 
            "WssId": "-1" // <-- always "-1" 
        }
    })
});

Delete

See delete section for hyperlink field.



Multiple Metadata (Taxonomy)

Create

We can not work with multi value taxonomy field like with single value one. To achieve this goal we need to do some tricks

First of all we have to reach Id of the hidden field which contains taxonomy value. Id of this field stored in taxonomy field property TextField:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/fields?$filter=InternalName eq 'MultiTerm&$select=TextField",
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

SharePoint returns Id of the hidden field we are looking for:


<feed>
    <entry>
        <content type="application/xml">
            <m:properties>
                <d:TextField m:type="Edm.Guid">7ec65949-1ecc-4b04-9a0e-da6282cd747b</d:TextField>
            </m:properties>
        </content>
    </entry>
</feed>

The next step is getting InternalName property of this hidden field:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/fields/getbyid(guid'7ec65949-1ecc-4b04-9a0e-da6282cd747b')?$select=InternalName",
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

We have InternalName which we need to update multi value taxonomy field:


<entry>
    <content type="application/xml">
        <m:properties>
            <d:InternalName>j9e7c67e91e64e8a8c26e61ec1e4007b</d:InternalName>
        </m:properties>
    </content>
</entry>

We know field which we need to update. Value for this field is string which we get by concatination following values: -1;#|TERMGUID1;#-1;#|TERMGUID2:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val() // <-- digest
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "j9e7c67e91e64e8a8c26e61ec1e4007b": "-1;#|d3ce8903-4b4e-442e-8f19-161bf45be9e8;#-1;#|33899e31-576e-4254-a9cf-d53bac59935a"
    })
});

Read

Read taxonomy field value via REST:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(11)?$select=MultiTerm", // <-- list item id
    type: "GET",
    headers: {
        "Content-Type": "application/json;odata=verbose"
    }
});

The response contains label values (not WssId):


<entry>
    <content type="application/xml">
        <m:properties>
            <d:MultiTerm m:type="Collection(SP.Taxonomy.TaxonomyFieldValue)">
                <d:element>
                    <d:Label>Demo</d:Label>
                    <d:TermGuid>d3ce8903-4b4e-442e-8f19-161bf45be9e8</d:TermGuid>
                    <d:WssId m:type="Edm.Int32">67</d:WssId>
                </d:element>
                <d:element>
                    <d:Label>Meeting</d:Label>
                    <d:TermGuid>33899e31-576e-4254-a9cf-d53bac59935a</d:TermGuid>
                    <d:WssId m:type="Edm.Int32">68</d:WssId>
                </d:element>
            </d:MultiTerm>
        </m:properties>
    </content>
</entry>

Label values are wrong only for single taxonomy field.

Update

Very similar to create operation:


$.ajax({
    url: "/_api/web/lists/getbytitle('CRUDList')/items(10)",
    type: "POST",
    headers: {
        "Content-Type": "application/json;odata=verbose",
        "X-RequestDigest": $("#__REQUESTDIGEST").val(), // <-- digest
        "X-HTTP-Method": "MERGE", // <-- for update request
        "IF-MATCH": "*" // <-- for update request
    },
    data: JSON.stringify({
        "__metadata": { "type": "SP.Data.CRUDListListItem" }, // <-- entity type name
        "j9e7c67e91e64e8a8c26e61ec1e4007b": "-1;#|d3ce8903-4b4e-442e-8f19-161bf45be9e8"
    })
});

Delete

See delete section for hyperlink field.


Share

Comments