Vitaly Zhukov' Blog

SharePoint List REST API. Part 2

July 18, 2018

SharePoint List REST API

The second part of the 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.

The 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 are very similar to text field ones. There is a 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. The server will do that itself before saving value into the 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)

The 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 the label.

Warning
SharePoint does not return the label of metadata single field via REST API.

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 a multi-value taxonomy field like with a 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 a 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.

Tags

#JavaScript #REST #JSOM #Git #Office 365 #jQuery #SharePoint 2016 #SharePoint #SharePoint Online

Share

Vitaly Zhukov

Vitaly Zhukov

Tech Lead, Architect, Developer, Technical Trainer, Microsoft MVP. Over 20 years of experience in system integration and software development. I specialize in designing and implementing scalable, high-performance software solutions across various industries.

You May Also Like

Call Dataverse API from SPFx Web Part

Call Dataverse API from SPFx Web Part

Provision Lists and Libraries with SPFx solution

Provision Lists and Libraries with SPFx solution

SharePoint. Drag-and-Drop File Uploading

SharePoint. Drag-and-Drop File Uploading

CSOM. Upload document

CSOM. Upload document

SharePoint Framework. Create Angular WebPart

SharePoint Framework. Create Angular WebPart

SharePoint List REST API. Part 1

SharePoint List REST API. Part 1

Project Server. CSOM + Custom Fields

Project Server. CSOM + Custom Fields

SharePoint 2010. Long time operation with updatable status

SharePoint 2010. Long time operation with updatable status

Linq to SharePoint. Cross site collection queries

Linq to SharePoint. Cross site collection queries

SharePoint. Getting Document Icon URL

SharePoint. Getting Document Icon URL

Linq to SharePoint. Repository pattern

Linq to SharePoint. Repository pattern

Linq to SharePoint vs Camlex.NET Performance Comparison

Linq to SharePoint vs Camlex.NET Performance Comparison

Linq to SharePoint. Part 5. Choice and MultiChoice fields

Linq to SharePoint. Part 5. Choice and MultiChoice fields

Linq to SharePoint. Part 4

Linq to SharePoint. Part 4

Linq to SharePoint. Part 3

Linq to SharePoint. Part 3

Linq to SharePoint. Part 2

Linq to SharePoint. Part 2

Linq to Sharepoint. Part 1

Linq to Sharepoint. Part 1