SharePoint List REST API. Part 2
SharePoint List REST API
- Working with lists and list items with REST
- Part 1 - Text, Boolean, Choice, MultiChoice, Lookup, MultiLookup, User, MultiUser
- Part 2 - Hyperlink, Metadata, MultiMetadata, DateTime (this post)
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.
Hyperlink
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.