What’s new and what’s changed in SharePoint Online REST API in January-February 2019

05 March 2019 Sergei-Sergeev REST API, SharePoint

I haven't posted about changes in REST API for a while, because nothing interesting was really happening inside REST API in December-November. But now we have something new to explore! 

Just a quick reminder, all data are coming 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

This item was in the roadmap for a while. You will be able to "mark" a site as "organizational news source". When viewing news from "organizational news source" you will see an indication that this news is "organization news". Nice feature to distinguish global company news from department news.

Now we can see that some work is done regarding this feature. There is a new root endpoint "SP.OrganizationNews" with alias "OrgNews":

{{site url}}/_api/OrgNews

Currently, for my tenant it returns nothing, it looks like this API is still in development. I expect that in future we will be able to use this endpoint to "mark" a site as "organizational news source". 

An interesting endpoint is below: 

{{site url}}/_api/OrgNews/SitesReference

It returns a collection of {siteId, webId}. In other words, it returns all sites, which were marked as "organizational news source". It returns an empty list for me, obviously because I don't have such sites at my tenant yet. I haven't found any API to create an Org News site reference. As said it's in development. 

Full Page Applications aka Single Part App Pages

You can convert any Site Page to a single part app page. This feature is still in preview, read more here - Using single part app pages in SharePoint Online. 

There is an API to get all site pages: 

{{siteUrl}}/_api/sitepages/Pages

Two new methods were added to the API - CreateFullPageAPp and UpdateFullPageApp. With this API you can easily create a new full-page application with predefined web part or update existing one (replace / update webpart). I've tested and it works! 

Here is how to create a new full-page app with custom developed web part:

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

{
    "webPartDataAsJson": "{\"id\":\"e6599e48-c875-4c0e-8b1f-abe2f54c1132\",\"instanceId\":\"9c6edb6e-199a-4a30-a3b6-73466a68187b\",\"title\":\"Full App Page testing wp\",\"description\":\"HelloWorld description\",\"dataVersion\":\"1.0\",\"properties\":{\"description\":\"HelloWorld\"}}",
    "title": "My-app",
    "addToQuickLaunch": true
}

A new page with url {{site url}}/SitePages/My-app.aspx will be created. 

here is webPartDataAsJson in a more readable form: 

{
	"id": "e6599e48-c875-4c0e-8b1f-abe2f54c1132",
	"instanceId": "9c6edb6e-199a-4a30-a3b6-73466a68187b",
	"title": "Full App Page testing wp",
	"description": "HelloWorld description",
	"dataVersion": "1.0",
	"properties": {
		"description": "HelloWorld"
	}
}

id is your webpart Id from webpart.manifest.json. instanceId - a guid, you should generate it, will be used as unique Id of your webpart at a page. To make it work you should install your SPFx solution with custom webpart to the site. Or instead, you can use OOB web parts. 

If you want to quickly find the value for id and properties parameter, you can use page maintenance mode. Open a site page, edit and add the desired webpart. Save, then append ?maintenancemode=true to the end of the page's url. You will details about all web parts on the page. 

How to update an existing full-page app (replaces a web part used on the page):

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

{
    "serverRelativeUrl": "/sites/dev/SitePages/My-app.aspx",
    "webPartDataAsJson": "{\"id\":\"e6599e48-c875-4c0e-8b1f-abe2f54c1132\",\"instanceId\":\"ac6edb6e-199a-4a30-a3b6-73466a68187b\",\"title\":\"Full App Page testing wp\",\"description\":\"HelloWorld description\",\"dataVersion\":\"1.0\",\"properties\":{\"description\":\"HelloWorld\"}}"
}

Now you know how to create/update full-page app before even Microsoft announced it :)

Additionally, a new root method was added to get all full page apps on a site: 

GET {{siteUrl}}/_api/SP.Publishing.SitePageService.GetAvailableFullPageApplications(true)
Accept: application/json;odata=nometadata

However, it returns empty results in my tenant despite a few full page apps created with CreateFullPageApps. Probably this API is still undergoing. 

Microsoft Teams and SharePoint Team Sites

Probably you noticed at your modern Team sites a prompt in the left bottom corner, which asks if you want to create a Team for your group.

This feature called "teamify", you can read more here - Top 10 most important powers of your SharePoint team sites in Office 365 (search for "teamify"). Now it's possible to ensure that Team is created for group-connected modern Team site with groupsitemanager API: 

POST {{siteUrl}}/_api/groupsitemanager/EnsureTeamForGroup
Accept: application/json;odata=nometadata

# RESPONSE

{
  "value": "https://teams.microsoft.com/l/team/19:05f5a2559b1e09fc2189fe%40thread.skype/conversations?groupId=5458e846-a19e-4ceb-9190-b7ba729ef216&tenantId=d2a410c1-dc63-444f-99b4-1a943e8c8d1d"
}

After this action, a new team will be created and a navigation link to the team will be added to the SharePoint Team site. Once again, it doesn't work for communication sites, only for group-connected team sites. 

There are methods to check if "teamify" prompt is visible and hide teamify prompt via REST API: 

POST {{siteUrl}}/_api/groupsitemanager/IsTeamifyPromptHidden
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

{
    "siteUrl": "https://contoso.sharepoint.com/sites/dev/"
}

### 


POST {{siteUrl}}/_api/groupsitemanager/HideTeamifyPrompt
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

{
    "siteUrl": "https://contoso.sharepoint.com/sites/dev/"
}

There is also an endpoint to "RestoreTeamsChannelSite" under spsitemanager as well:

POST {{siteUrl}}/_api/spsitemanager/RestoreTeamsChannelSite
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

{
    "siteId":"d15a00c4-d516-4f2b-9384-4d5cb5b5e932",
    "relatedGroupId":"5458e846-a19e-4ceb-9190-bdba729ef216"
}

Additionally, you have an option to get and set team channel owners for group-connected team site (it seems that these methods are also in development):

### GetTeamChannelSiteOwner
GET {{siteUrl}}/_api/spsitemanager/GetTeamChannelSiteOwner('<site id>')
Accept: application/json;odata=nometadata

### SetTeamChannelSiteOwner
POST {{siteUrl}}/_api/spsitemanager/SetTeamChannelSiteOwner
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

{
    "siteId": "d15a00c4-d516-4f2b-9384-4d5cb5b5e932",
    "logonName": "john@contoso.com"
}

Group-connected SharePoint Team sites

If a site is a group connected team site, you now are able to get corresponding group id via property "RelatedGroupId"

GET {{siteUrl}}/_api/site?$select=RelatedGroupId
Accept: application/json;odata=nometadata

Modern Document Sets

SP.Directory.User type received a property called "sharePointModernDocSetsFirstRun". Which basically means that we will see modern documents sets pretty soon :).

Site Designs

Some new interesting methods were added to SiteScriptUtility: 

  • GetDesignPackageMenuContents
  • GetHiddenBuiltInDesignPackages
  • SetBuiltInDesignPackageVisibility

They were mentioned at New SharePoint CSOM version released for SharePoint Online – February 2019 post - just on a moment when I was creating this post. 

It appeared that it's just a new name for design selection when you create a modern site (topic, showcase, etc.) It looks like now it's possible to hide some designs from dropdown using SetBuiltInDesignPackageVisibility method. Also, I expect that more built-in designs are coming. 

Migration

I noticed a lot of changes in *Migration* namespace. A lot of new changes were introduced, please read it here - New and improved features in the SharePoint Migration Tool (SPMT).

Some other findings

spsitemanager received a method called SiteUrl. You can resolve full site url by its Id: 

GET {{siteUrl}}/_api/spsitemanager/SiteUrl('d15a00c4-d516-4f2b-9384-4d5cb5b5e932')
Accept: application/json;odata=nometadata

# RESPONSE

{
  "value": "https://contoso.sharepoint.com/sites/hr"
}

SP.User received a new property "UserPrincipalName"

GET {{siteUrl}}/_api/web/CurrentUser?$select=UserPrincipalName
Accept: application/json;odata=nometadata

SP.Web received a property "PageContextCore"

It looks like it's a base for "PageContextInfo" request:

GET {{siteUrl}}/_api/web/PageContextInfo
Accept: application/json;odata=nometadata

It returns a ton of useful information about the current web (including request digest for example). "PageContextCore" returns request digest and user name only. 

That was an overview of SharePoint REST API changes in Jan-Feb 2019. Dig into the full details by your own at API Changelog.