Office 365 Groups REST API

The simple goal of Office 365 groups is to “bring together people, information and apps to enable better communication and collaboration”. Some of the key benefits of using groups are:

• It allows you to get started instantly and use anywhere in Office. You can see them already in products such as Outlook Web Access and soon in the latest Desktop Outlook
• They are public by default which enables users to discover and join new Groups easily
• Easier to manage membership and permissions in one place both for end users and IT administrators
• Private groups provide the flexibility to control access to your group
• Invite someone to just participate in a conversation or share a file, without including them in the Group itself
• New members can get started quickly, with full context and history of all the information shared with the Group

Groups are defined and managed in Azure Active Directory, delivering collaboration experiences across Office 365 and beyond due to its extensibility.

Think of the Groups as a layer that stitches together multiple workloads like Outlook Conversations and Calendar, OneDrive Files, OneNote and soon many more like Skype, Delve, Dynamics CRM. And with Apps being built on top of them, they offer rich extensibility as a platform. In fact, the recently announced Microsoft Class Dashboard is built on the Groups REST API; a great testament to the fact that even internally we are betting on platform and the APIs for large scale applications.

Office 365 Unified API

Now that we have some context on what groups are, let’s look at the APIs to access them.

Office 365 Groups API access is through the Unified APIs. The unified APIs offer a single REST API endpoint to access multiple office workloads, such as mail, calendar, contacts, files and now groups. It offers the simplicity of using one app registration, one authentication and authorization, one unified metadata, client libraries and more.

Groups API – Features

There are essentially four things you can do with Groups API today:

• Management
• Conversations
• Events (Calendar)
• Files

Let’s look at each of them briefly with some sample calls to understand the programming model.

Management

The base URL to access groups is:

  https://graph.microsoft.com/beta/contoso.com/groups  

You can also use the alias “myorganization” instead of your actual tenant identifier to resolve to the signed-in user’s tenant. So the above URL can also be written as:

  https://graph.microsoft.com/beta/myorganization/groups  

From here you can essentially Create, modify, Read and Delete Groups. Here are a couple of examples to give a flavor of group management. See the management API documentation to learn about all the capabilities.

• To create a Group, you do a POST on the groups endpoint with the group properties.

  POST https://graph.microsoft.com/beta/contoso.com/groups  Content-Type: application/json    {      "groupType": "Unified",      "displayName": "REST API Builders",      "mailNickname": "restandbuild",      "mailEnabled": "true"  }  

• To see all the Office 365 groups, which you are a member of you can use the ‘joinedgroups’ property on the user.

  https://graph.microsoft.com/beta/me/joinedgroups  

Note that ‘me’ is an alias representing the signed-in user, just like ‘myorganization’ is for the signed-in user’s tenant.

Conversations

Group conversations are the way to communicate in the group. Any message you post to a group is part of a conversation. Conversations have a nested hierarchy, where conversations contain threads and threads contain Posts.

Here are a couple of sample group conversation requests. See full documentation for all the available capabilities.

To view all the conversations in a group you can enumerate the /conversations collection:

  https://graph.microsoft.com/beta/contoso.com/groups/{groupId}/conversations  

• To create a new conversation, you POST to the same collection:

  POST https://graph.microsoft.com/beta/contoso.com/groups('c75831bd-fad3-4191-9a66-280a48528679')/Conversations  Content-Type: application/json  {      "Topic": "Hello Pluto!",      "Threads": [          {              "Posts": [                  {                      "Body": {                          "ContentType": "HTML",                          "Content": "brrrr!!"                      }                  }              ]          }      ]  }  

• The basic URL pattern to follow with conversations, to navigate to its nested entities is:

  https://graph.microsoft.com/beta/contoso.com/groups/{groupId}/conversations/{convId}/threads/{threadId}/posts/{postId}

Calendar

Group Calendar uses exactly the same API shapes as the Me/Calendar. Please see the group calendar documentation for all possible requests.

The only difference between me/calendar and group calendar is that in group calendar you cannot ‘Accept’, ‘Tentatively Accept’ or ‘Decline’ a group event. You will receive a HTTP 400 response code with an error.

  "error":  {      "code": "ErrorInvalidRequest",      "message": "Your request can't be completed. Group mailbox cannot respond to events."    }  

All events that are sent to a group calendar are automatically ‘Accepted’.

Files

Similar to Group calendar, the group files are also similar to me/files. You can create, update, delete and read Files and File folders.

Base URL for files:

  https://graph.microsoft.com/beta/contoso.com/groups/{groupid}/files  

Create a new file:

  POST https://graph.microsoft.com/beta/contoso.com/groups/{groupid}/files  {     "name": "newFile.txt",    "type": "File"  }  

Update an existing file (use it to add content to a file):

  PUT https://graph.microsoft.com/beta/contoso.com/groups/{groupsid}/files/{fileid}/content  Content-Type: text/plain    This is text for the example content.  

Gotchas/Upcoming Improvements

1. Instant-On:Today when you create a group using the Unified API, it might take minutes for the group to get provisioned and for you to start using say conversations or files within the group. This is a sub-par experience, because as a developer, you want to be able to start interacting with the group as soon as you have created it. The engineering team is working to get this functionality enabled. As soon as we have it ready and rolled out, we will announce it.
2. Get/Set Group Photo:You can see and set them using outlook web access, so why not using the API. This one is very close to done. You should start seeing group photo very soon in the APIs.
3. Operate at thread level:: One other feedback we heard from early adopters was that they wanted to operate at only one level of nesting for conversations. Instead of having to go through
   • Group->conversations->threads->Posts, they want to be able to do
   • Group->threads->Posts

This takes away some complexity if your UI does not require you to have two levels of nesting for Posts. The engineering team is working to allow you to do all conversation activity at the thread level and if your app does not need, then it can totally skip the /conversations collection.

For example:

  GET 	../groups/{groupid}/threads (to enumerate all threads in a group)  POST 	../groups/{groupid}/threads (to create a new thread)  

Thanks for taking the time. Feel free to provide any feedback and comments. Our engineering team monitors the stackoverflow office365 tag very closely, please reach out to us if you have any questions regarding the APIs.