What’s new and what’s changed in SharePoint Online REST API in March-April 2019

REST API
5 min read
#rest api #sharepoint #api-changelog

What’s new and what’s changed in SharePoint REST API in March in April 2019? Explore the most interesting changes (additions and updates) here! 

Just a quick reminder, all data come from my SharePoint REST API Metadata Explorer. Go to the “API Changelog” tab and see what’s changed in recent months in SharePoint REST API. 

Disclaimer

Please note, that all changes are gathered from Targeted tenant. Most likely these changes haven’t been officially introduced yet, use this post as spoilers to potential upcoming features. If you want to use APIs mentioned here in production, please check corresponding official documentation to make sure they are available.

Organizational News (aka authoritative news)

In the previous episode, I mentioned that OrgNews endpoint was added. Now, when corresponding PowerShell cmdlets (Get-SPOOrgNewsSite, Set-SPOOrgNewsSite, Remove-SPOOrgNewsSite) to manage Organizational news sources (also known as authoritative news) were announced, you can also use REST API to list all organizational news sources. However, I haven’t found a way to add or remove authoritative news sources using the REST API.

List all authoritative news sources:

GET {{siteUrl}}/_api/OrgNews/SitesReference
Accept: application/json;odata=verbose

In addition to PowerShell, you can manage authoritative news sources with CSOM.

Read more about authoritative news here.

Organizational Assets Library

Organization assets let you register one or more document libraries via PowerShell as a special source for images, such as photos and logos, across all sites. The Organization assets libraries are available when you add images to page headers, galleries, or other web parts

With SetOrgAssetsLib endpoint you can set a library to be an organizational assets library. It’s also available in CSOM. Read more about organizational assets library here. 

SP.FieldThumbnail

It seems a new field type is coming to SharePoint Online. There is a chance, that it was introduced to support internal scenarios, but maybe not. 

Get Site Script from web!

This is something really interesting. You know, that it’s possible to create site script from a list:

POST {{siteUrl}}/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteScriptFromList
Accept: application/json;odata=verbose
Content-Type: application/json

{
    "listUrl": "https://<org>.sharepoint.com/sites/dev/Lists/Clients"
}

It returns valid site script with createSPList action with all data needed to re-create target list. 

In April 2019 SiteScriptUtility also received a method called GetSiteScriptFromWeb. It means that we will have an option to generate a site script from the entire web! Here is how the request looks like:

POST {{siteUrl}}/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GetSiteScriptFromWeb
Accept: application/json;odata=verbose
Content-Type: application/json

{
    "webUrl": "https://<org>.sharepoint.com/sites/dev",
    "info": {
        "IncludeBranding": true,
        "IncludedLists": ["Clients", "MyList"],
        "IncludeRegionalSettings": true,
        "IncludeSiteExternalSharingCapability": true,
        "IncludeTheme": true
    }
}

Unfortunately, it doesn’t work yet, the error says “The requested operation is part of an experimental feature that is not supported in the current environment.” But I expect that in future it will be fully functional (maybe with some additions).

Full Page Applications aka Single Part App Pages

Two new methods were added to manage Full Page Apps - CreateAppPage and UpdateAppPage. In the previous episode, I mentioned CreateFullPageApp and UpdateFullPageApp. These two newly added do exactly the same with a slightly different parameter set. To be honest I don’t know the exact reason why two identical methods were introduced and which one is “official” one. 

Consider the difference:

Let’s say I want to create a single app page with count down timer web part.

CreateFullPageApp

POST {{siteUrl}}/_api/sitepages/Pages/CreateFullPageApp
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

{
    "webPartDataAsJson": "{\"id\":\"62cac389-787f-495d-beca-e11786162ef4\",\"instanceId\":\"9c6edb6e-199a-4a30-a3b6-73466a68187b\",\"title\":\"Full App Page Countdown Timer\",\"description\":\"This web part is used to allow a site admin to count down/up to an important event.\",\"dataVersion\":\"1.0\",\"properties\":{\"showButton\":false,\"countDate\":\"Mon May 13 2019 14:00:00 GMT+0100\",\"title\":\"My count down\",\"description\":\"\",\"countDirection\":\"COUNT_DOWN\",\"dateDisplay\":\"DAY_HOUR_MINUTE_SECOND\",\"buttonText\":\"\"}}",
    "title": "Full-Page1",
    "addToQuickLaunch": true
}

Where webPartDataAsJson is

{
	"id": "62cac389-787f-495d-beca-e11786162ef4",
	"instanceId": "9c6edb6e-199a-4a30-a3b6-73466a68187b",
	"title": "Full App Page Countdown Timer",
	"description": "This web part is used to allow a site admin to count down/up to an important event.",
	"dataVersion": "1.0",
	"properties": {
		"showButton": false,
		"countDate": "Mon May 13 2019 14:00:00 GMT+0100",
		"title": "My count down",
		"description": "",
		"countDirection": "COUNT_DOWN",
		"dateDisplay": "DAY_HOUR_MINUTE_SECOND",
		"buttonText": ""
	}
}

As a result, a full-page app with url “Full-Page2.aspx” is created inside the Site Pages library. 

CreateAppPage

POST {{siteUrl}}/_api/sitepages/Pages/CreateAppPage
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata
X-RequestDigest: {{digest}}

{
    "webPartDataAsJson": "<JSON data>"
}

Here it creates a page with a unique generated name, check out-ed to you:

If you want to change the page url and include it in navigation, you should update it further with

UpdateAppPage

POST {{siteUrl}}/_api/sitepages/Pages/UpdateAppPage
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata
X-RequestDigest: {{digest}}

{
    "webPartDataAsJson": "<JSON data>",
    "title": "Full-Page3",
    "includeInNavigation": true,
    "pageId": 20
}

These two new methods (CreateAppPage and UpdateAppPage) when used together consistently do the same as one method CreateFullPageApp. 

SitePages endpoint enhancements 

Some endpoints were added recently, some were added a few months ago, however, I haven’t mentioned them here. 

Copy vs CreateNewsCopy

There are two methods to copy a site page or a news page. Both work very similarly and I haven’t found any significant differences. Just be aware that there is CreateNewsCopy method, which intended to be used for News pages:

POST {{siteUrl}}/_api/sitepages/Pages/GetById(21)/CreateNewsCopy
Accept: application/json;odata=verbose
Content-Type: application/json

It creates a page with a temporary unique name (f3la4a.aspx), you should update it and provide a title. 

Promote and Demote News

You can promote a page as a news page using below API call:

POST {{siteUrl}}/_api/sitepages/Pages/GetById(21)/PromoteToNews
Accept: application/json;odata=verbose
Content-Type: application/json

After this call, your news post will appear in news web parts. DemoteFromNews is supposed to do vice versa, however, for some reason, it doesn’t work (throws Invalid number value exception). 

SavePageAsTemplate

POST {{siteUrl}}/_api/sitepages/Pages/GetById(21)/SavePageAsTemplate
Accept: application/json;odata=verbose
Content-Type: application/json

This method creates a template out of your page and puts into the “Templates” folder in Site Pages library. Page templates were introduced recently, check out this video to learn more.

This is it, as usual, you can explore the full list of changes on your own at API Changelog.