Navigate the SharePoint data structure represented in the REST service
Learn how to start from a REST endpoint for a given SharePoint item, and navigate to and access related items, such as parent sites or the library structure where that item resides.
Note The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.
Navigate from a given URL to reach other SharePoint resources
When you're working with the SharePoint REST service, you'll often start out knowing the URL of a specific SharePoint item, but want to access related items, such as the folder or library structure where that item resides. For example, suppose you create an add-in where your user enters the URL of a document in a SharePoint library. Your add-in must then break down that URL to figure out the actual SharePoint site URL. Once it's done that, the add-in can then make more requests from the site on the user's behalf, such as to create, update, or delete related items or resources.
To do this, your add-in needs to query SharePoint for the following information:
The server relative URLs of the site and site collection containing the resource
A form digest to enable you to perform requests that change the state of the resource, such as POST, PUT, MERGE, and DELETE
The basic process:
/contextinfooperator with the given URL to access the site and site collection addresses, and the form digest. Use the
/contextinfooperator in the following format:
To increase security against cross-site scripting attempts, the
/contextinfooperator accepts only POST requests.
Use the SPContextWebInformation object properties that the
/contextinfooperator returns to access additional resources as desired.
Start with a URL to a given SharePoint item. For example:
Remove the name of the specific resource from the end of the URL, so that the URL points to a document library, folder, or list. IN this case:
Append the REST service pointer and the
/contextinfooperator to the URL:
Read the form digest and webFullUrl properties from the response.
Append the REST service pointer
_apito the web URL
Use the resulting URL and the form digest to make requests for other resources you need.
You don't have to pass the form digest if you're making GET requests, or making requests using a validated OAuth token.
Navigate parent and child sites
When you navigate your site structure using the SharePoint server object model, you use the SPWeb.ParentWeb and SPWeb.Webs properties to access objects that represent parent and child sites.
The corresponding REST resources—
web/webs—don't return objects that represent sites. This is because the REST service conforms to OData standards, and returning complete site representations would make such requests inefficient. Instead, they return a WebInfo object that contains the site's scalar properties, but without related entity sets such as like collections or field collections.
To navigate to a specific parent or child site, construct the appropriate REST URL to that site using the Id or Title property to. From there, you can access that site's related entity sets.
Navigating folder structure
The SharePoint REST service does not support traversing the folder hierarchy of a site through the URL construction. Instead, use the REST equivalent of the Web.GetFolderByServerRelativeUrl method. For example:
Navigation not supported through the REST service:
Navigation that is supported by the REST service:
SPContextWebInformation object properties
|webFullUrl||Gets the server-relative URL of the nearest site.|
|siteFullUrl||Gets the server-relative URL of the root of the site collection that the site is contained within.If the nearest web is the root of a site collection, then the value of the webFullUrl property is equal to the siteFullUrl property.|
|formDigestValue||Gets the server's request form digest.|
|LibraryVersion||Gets the current version of the REST library.|
|SupportedSchemaVersions||Gets the versions of the schema of the REST/CSOM library that are supported.|
|Created||Gets a value that specifies when the site was created.|
|Description||Gets or sets the description for the site.|
|Id||Gets a value that specifies the site identifier.|
|Language||Gets a value that specifies the locale ID (LCID) for the language that is used on the site.|
|LastItemModifiedDate||Gets a value that specifies when an item was last modified in the site.|
|Title||Gets or sets the title for the site.|
|WebTemplateId||Gets the identifier of the site template.|