Wednesday, 26 July 2017

Working with the Page Comments REST API in SharePoint Communication sites

If you have been playing around with SharePoint Communication sites, you might have noticed there is commenting functionality available now on site pages. Digging deeper on how this functionality is implemented gives us some interesting findings!

There is a Comments REST API available which is used to get and post comments for a particular page. This endpoint is an addition to the SharePoint REST API, which means you will already be familiar with using it.

I checked with Vesa Juvonen from Microsoft and he has confirmed this is indeed a public API, which means it can be used in third party solutions and is not something internal used only by Microsoft.


There are a few interesting things about how the commenting solution is implemented:
  1. Comments are not stored in the page list item (which makes sense in terms of scalability). They appear to be stored in a separate data store.
  2. Comments are stored with references to list guids and item ids. This means that if you move or copy a page, comments for that page will be lost.
  3. Only a single level of replies is allowed. Which in my opinion is a good thing as this will prevent long winding conversations and force users to keep their comments brief.

Now lets have a look at the SharePoint Comments REST API:

1) Get comments for a page:

/_api/web/lists('1aaec881-7f5b-4f82-b1f7-9e02cc116098')/GetItemById(1)/Comments

This will bring back all the top level comments for a page which has the id 1 and lives in a site pages library with guid "1aaec881-7f5b-4f82-b1f7-9e02cc116098". 

2) You can also use the list title to get the list and the comments:

/_api/web/lists/GetByTitle('Site Pages')/GetItemById(1)/Comments

3) Get replies for each comment:

/_api/web/lists('1aaec881-7f5b-4f82-b1f7-9e02cc116098')/GetItemById(1)/Comments?$expand=replies

4) Get replies for a specific comment:

/_api/web/lists('1aaec881-7f5b-4f82-b1f7-9e02cc116098')/GetItemById(1)/Comments(2)/replies

Where 2 is the id of the comment. 

5) Post a new comment on a page by making a POST request to:

/_api/web/lists('1aaec881-7f5b-4f82-b1f7-9e02cc116098')/GetItemById(1)/Comments

6) To Delete a comment or a reply, Make a DELETE request to:

/_api/web/lists('1aaec881-7f5b-4f82-b1f7-9e02cc116098')/GetItemById(1)/Comments(2)

Since each comment or reply gets a unique id, the method is same for deleting both.

Here is some sample code I put together to use the Comments REST API in an SPFx webpart:


Get comments for a page:



Post a comment on a page:


Code for this web part available on GitHub: https://github.com/vman/spfx-sitepage-comments/

Quick note about running the webpart on the SharePoint Workbench: If the page on which you want to read or post comments lives in a communication site with url:

https://tenant.sharepoint.com/sites/comms/SitePages/ThisIsMyPage.aspx

Then make sure you are running the workbench from the same site:

https://tenant.sharepoint.com/sites/comms/_layouts/15/workbench.aspx

Hope you found this post interesting!

1 comment:

Giuliano De Luca said...

Good catch well done!