Edit

Working with SharePoint sites in Microsoft Graph

  • Article
  • 2 minutes to read

The SharePoint API in Microsoft Graph supports the following core scenarios:

  • Access to SharePoint sites, lists, and drives (document libraries)
  • Read-only support for site resources (no ability to create new sites)
  • Read-write support for lists, listItems, and driveItems
  • Address resources by SharePoint ID, URL, or relative path

The SharePoint API exposes three major resource types:

The following is an example of a listItem resource.

{
  "fields": {
    "Title": "Access card",
    "Employee": "Ryan Gregg",
    "EmployeeId": "10",
    "CardSerial": "01235492",
    "Alias": "RGregg",
    "ID": 1,
    "ContentType": "Item",
    "Modified": "2016-09-19T23:15:25-07:00",
    "Created": "2016-09-19T23:15:25-07:00"
  },
  "createdBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "createdDateTime": "2016-09-20T06:15:25Z",
  "eTag": "48e941c3-9515-4c48-9760-c07c90c79d48,1",
  "id": "4",
  "lastModifiedBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "lastModifiedDateTime": "2016-09-20T06:15:25Z",
}

Resources expose data in three different ways:

  • Properties (like id and name) expose simple values.
  • Facets (like fields and createdBy) expose complex values.
  • References (like items) point to collections of other resources.

You can expand references in your URL with the expand query parameter; for example, ?expand=fields. You can request specific properties and facets with the select query parameter; for example, ?select=id,name. By default, most properties and facets are returned while all references are hidden. For efficiency, we recommend that you specify select and expand to only return the data you care about.

SharePoint API root resources

The following examples are relative to https://graph.microsoft.com/beta.

Path Description
/sites/root Organization's default site.
/sites/{site-id} Access a specific site by its ID.
/sites/{site-id}/drive Access the default drive (document library) for the given site.
/sites/{site-id}/drives Enumerate the drives (document libraries) under the site.
/sites/{site-id}/sites Enumerate the sub-sites under the site.
/sites/{site-id}/lists Enumerate the lists under the site.
/sites/{site-id}/lists/{list-id}/items Enumerate the listItems under the list.
/groups/{group-id}/sites/root Access a group's team site.

Sites can also be addressed by path by using the SharePoint hostname, followed by a colon and the relative path to the site. You can optionally transition back to addressing the resource model by putting another colon at the end.

Path Description
/sites/contoso.sharepoint.com:/teams/hr The site associated with https://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive Access the default drive for this site.

Note for existing SharePoint developers

The Microsoft Graph SharePoint API has a few key differences with the CSOM APIs. The site resource maps to SPWeb. The root site (SPWeb) in a site collection has a siteCollection facet, which contains information about the SPSite. Because IDs for sites are only unique within their site collection, addressing a site by ID requires providing both the site collection identifier and the site identifier.

GET https://graph.microsoft.com/beta/sites/{hostname},{spsite-id},{spweb-id}/

A URL constructed with only the hostname will point to the root site (SPWeb) in the default site collection.

GET https://graph.microsoft.com/beta/sites/{hostname}

A URL constructed with only the hostname and siteCollection (SPSite) ID will point to the root site (SPWeb) in the given site collection.

GET https://graph.microsoft.com/beta/sites/{hostname},{spsite-id}

What's new

Find out about the latest new features and updates for this API set.