Navigate the SharePoint data structure represented in the REST service

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. After 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

1. Use the /contextinfo operator with the given URL to access the site and site collection addresses, and the form digest. Use the /contextinfo operator in the following format:

   POST https://{site_url}/_api/contextinfo
   Authorization: "Bearer " + accessToken
   Accept: "application/json;odata=verbose"
   

   To increase security against cross-site scripting attempts, the /contextinfo operator accepts only POST requests.

2. Use the SPContextWebInformation object properties that the /contextinfo operator returns to access additional resources as desired.

Try it

1. Start with a URL to a given SharePoint item. For example: https://{site_url}/doclib/myDocument.docx

2. 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: https://{site_url}/doclib/

3. Append the REST service pointer and the /contextinfo operator to the URL:

   POST https://{site_url}/_api/doclib/contextinfo
   Authorization: "Bearer " + accessToken
   Accept: "application/json;odata=verbose"
   

4. Read the form digest and webFullUrl properties from the response.

5. Append the REST service pointer _api to the web URL.

6. Use the resulting URL and the form digest to make requests for other resources you need.

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/parentweb and 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 by using the Id or Title property. From there, you can access that site's related entity sets.

Navigate 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:

https://{site_url}/_vti_bin/client.svc/web/lists/SharedDocuments/folder1/stuff/things/Recycle

Navigation that is supported by the REST service:

https://{site_url}/_vti_bin/client.svc/web/GetFolderByServerRelativeUrl('SharedDocuments/folder1/stuff/things')/Recycle

SPContextWebInformation object properties

WebInfo object

See also

• Get to know the SharePoint REST service
• Use ETag values through the REST service to get document list item versioning
• OData resources
• Develop SharePoint Add-ins