Create, update, and delete list and library data with the SharePoint REST API
In this unit, you'll extend what you learned in a previous unit from just reading SharePoint list data to writing data using the SharePoint REST API. You'll learn how to create, update, and delete data in SharePoint lists and libraries in SharePoint Framework components with the SharePoint REST API.
Write operations in SharePoint Framework projects with the SharePoint REST API
The operations referred to when reading and writing data is simplified to CRUD operations. CRUD stands for create, read, update, and delete. A previous unit covered reading data from SharePoint lists. To request data from SharePoint's REST API, you use the get()
method on the SPHttpClient
API from the SharePoint Framework API.
When writing data to SharePoint lists and libraries, you most submit HTTP POST requests. This is done using the post()
method on the SPHttpClient
API. The get()
and post()
methods have the exact same arguments, although each scenario might require more steps.
For example, when updating or deleting an item in a SharePoint list, you should include the IF-MATCH
HTTP request header. You should also include the X-HTTP-METHOD
when updating and deleting SharePoint list items as well. These two request headers are covered in more detail in the sections on updating and deleting items later in this unit.
When creating or updating a SharePoint list item, you must submit the data for the new or updated item. This is done by including a JSON object that represents the new or updated item as a string in the body of the request. This object should also indicate what type of data its using the @odata.type
property. This is covered in more detail in the sections on creating and updating list items later in this unit.
Create SharePoint list items with the SharePoint REST API
You must tell the SharePoint REST API the data type of the item submitted in the request payload when you create a new list item. To do this, specify the data type in the @odata.type
property in the payload of the request.
This is required as SharePoint lists can support multiple content types. Each content type can have unique or shared fields, but each field can have different settings, such as if they're required or not. So, when creating an item, you must tell SharePoint the type of data so SharePoint knows which content type rules to enforce.
You can obtain a list of all the data types supported on a list using the lists ListItemEntityTypeFullName
property. It will return the data type supported by the list.
Let's look at an example. This TypeScript method requests the data type for the Countries list. It does this by requesting the ListItemEntityTypeFullName
property on the list and returning it back as a string in a JavaScript promise:
private async _getItemEntityType(): Promise<string> {
const endpoint: string = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items?$select=Id,Title`;
const response = await this.context.spHttpClient.get(
endpoint,
SPHttpClient.configurations.v1);
if (!response.ok) {
const responseText = await response.text();
throw new Error(responseText);
}
const responseJson = await response.json();
return responseJson.ListItemEntityTypeFullName;
}
Call this method before creating a new list item. The following TypeScript method calls the _getItemEntityType()
method to first get the data type supported by the list. It then creates a JSON object for the new item, setting the Title
property of the item and the @odata.type
property:
private async _addListItem(): Promise<SPHttpClientResponse> {
const itemEntityType = await this._getItemEntityType();
/* eslint-disable @typescript-eslint/no-explicit-any */
const request: any = {};
request.body = JSON.stringify({
Title: new Date().toUTCString(),
'@odata.type': itemEntityType
});
/* eslint-enable @typescript-eslint/no-explicit-any */
const endpoint = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items`;
return this.context.spHttpClient.post(
endpoint,
SPHttpClient.configurations.v1,
request);
}
Once the item is created, the object is converted to a JSON string using the JSON.stringify()
method, which is set to the body
property of the request. Notice in the SPHttpClient.post()
method, the third argument passed into the method is the request.
Update SharePoint list items with the SharePoint REST API
Updating list items with the SharePoint REST API is similar to creating items with a few small differences.
To update an item, you can submit an HTTP PUT or HTTP MERGE operation to the SharePoint REST API. The difference between the two is that PUT will update all properties on the specified item while MERGE will only update those properties included in the body of the request. This means that any properties omitted when submitting an HTTP PUT will be nulled out because no value was submitted.
If this isn't the behavior you want, you can use the HTTP MERGE method, which will ignore any properties not included in the body of the payload.
The challenge with the HTTP MERGE method is that not all networking equipment and libraries support it. To get around this limitation, specify the wanted method in an HTTP POST with the HTTP request header X-HTTP-METHOD
. Set the X-HTTP-METHOD
to MERGE
when you submit an HTTP POST using the SPHttpClient.post()
method when you want the SharePoint REST API to treat the HTTP POST as an HTTP MERGE.
When you update an item, you need to be sure that you're updating same version of the item that is on the server. In other words, you don't want to update an item that has changed since you previously retrieved it, otherwise you would overwrite another user's changes.
To protect against this scenario, use the IF-MATCH
HTTP request header and set its value to the etag of the current item. The etag is a unique string for the specific version of the item. If the etag matches the etag of the item on the server, the update is applied. If the etags don't match, the SharePoint REST API will return an HTTP error code 419 indicating the expected etag didn't match.
The following TypeScript method demonstrates how to update an item in a SharePoint list. After you obtain an item from a list, it then modifies the returned object's Title
property. Next, the two HTTP request headers IF-MATCH
and X-HTTP-METHOD
are added as previously discussed.
Finally, the request
object's body
property is set with the JSON string version of the object. Notice that unlike creating an item, the endpoint of the request includes the unique endpoint of the item to be updated:
private async _updateListItem(): Promise<SPHttpClientResponse> {
const getEndpoint: string = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items?` +
`$select=Id,Title&$filter=Title eq 'United States'`;
const getResponse = await this.context.spHttpClient.get(
getEndpoint,
SPHttpClient.configurations.v1);
if (!getResponse.ok) {
const responseText = await getResponse.text();
throw new Error(responseText);
}
const responseJson = await getResponse.json();
const listItem: ICountryListItem = responseJson.value[0];
listItem.Title = 'USA';
/* eslint-disable @typescript-eslint/no-explicit-any */
const request: any = {};
request.headers = {
'X-HTTP-Method': 'MERGE',
'IF-MATCH': (listItem as any)['@odata.etag']
};
/* eslint-enable @typescript-eslint/no-explicit-any */
request.body = JSON.stringify(listItem);
const postEndpoint: string = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items(${listItem.Id})`;
return this.context.spHttpClient.post(
postEndpoint,
SPHttpClient.configurations.v1,
request);
}
Delete SharePoint list items with the SharePoint REST API
Deleting list items with the SharePoint REST API is similar to updating items with a few small differences.
The SPHttpClient
API doesn't include a delete()
method like the get()
and post()
methods. Instead, to submit an HTTP DELETE request, you'll use the X-HTTP-METHOD
HTTP request header and set it to DELETE
. Similar to how you update an item, this will tell the SharePoint REST API to treat the HTTP POST as an HTTP DELETE request.
You can also use the IF-MATCH
HTTP request header to be sure you're deleting same version of the item that is saved in the SharePoint list. The other option is to ignore the version by setting the value of the IF-MATCH
header to *
, which you don't care what version is on the server.
The following TypeScript method demonstrates how to delete an item in a SharePoint list. After first obtaining an item from a list, it then modifies the request using the HTTP request headers IF-MATCH
and X-HTTP-METHOD
are added as previously discussed.
private async _deleteListItem(): Promise<SPHttpClientResponse> {
const getEndpoint = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items?` +
`$select=Id,Title&$orderby=ID desc&$top=1`;
const getResponse = await this.context.spHttpClient.get(
getEndpoint,
SPHttpClient.configurations.v1);
if (!getResponse.ok) {
const responseText = await getResponse.text();
throw new Error(responseText);
}
const responseJson = await getResponse.json();
const listItem: ICountryListItem = responseJson.value[0];
/* eslint-disable @typescript-eslint/no-explicit-any */
const request: any = {};
request.headers = {
'X-HTTP-Method': 'DELETE',
'IF-MATCH': '*'
};
/* eslint-enable @typescript-eslint/no-explicit-any */
request.body = JSON.stringify(listItem);
const postEndpoint = this.context.pageContext.web.absoluteUrl +
`/_api/web/lists/getbytitle('Countries')/items(${listItem.Id})`;
return this.context.spHttpClient.post(
postEndpoint,
SPHttpClient.configurations.v1,
request);
}
Summary
In this unit, you extended what you learned in a previous unit from just reading SharePoint list data to writing data using the SharePoint REST API. You learned how to create, update, and delete data in SharePoint lists and libraries in SharePoint Framework components with the SharePoint REST API.