Retrieve available web templates and create a subsite with Office 365 REST API

When you work with the Office 365 REST API, especially with SharePoint parts of the API, you will probably need at a given time, to create subsites in a site collection.

If you don’t know how to achieve this goal, we will explain in this article how to do it.

How to create a subsite ?

It exists 2 different ways to create subsites in a site collection with REST API. You need to submit an HTTP POST request to one of the following endpoints :

https://<tenant>.sharepoint.com/_api/Web/Webs/Add

http://<tenant>.sharepoint.com/_api/Web/WebInfos/Add

Each endpoint has its own format to submit information to SharePoint to create the site.

In our following example, we will use the first endpoint. If you want more information for the second, please refer to https://msdn.microsoft.com/EN-US/library/office/jj164022.aspx#bk_CreateSite.

To be able to create a site, SharePoint needs some information such as the title, the description, the template and the URL. These information have to be submitted in the body of the HTTP POST request in the following format.

 {
    "parameters":
    {
        "Title":"Sample Team Site",
        "Description":"The description of our new team site",
        "WebTemplate":"STS#0",
        "Url":"SampleTeamSite"
    }
}

As you can see, you have to indicate the name of an available web template. I’m pretty sure that you’re asking yourself, what are the possible values ?

Retrieve the list of available templates

The Office 365 REST API has all the necessary things to retrieve the list of templates available in your Office 365 tenant.

To retrieve the list of these templates, you just have to submit an HTTP GET request to the following endpoint. You need to specify in which language (1033 = English, 1036 = French…) you want to retrieve the templates (with localized titles, descriptions…).

https://<tenant>.sharepoint.com/_api/Web/GetAvailableWebTemplates(lcid=1033)

When you will execute the request above and check the response, you will see a lot of templates. All of them should not be used because they are deprecated, are system templates, etc…

It’s possible to filter the list to only retrieve usable templates by specifying additional parameters in the querystring as you can see below and by using the OData syntax supported by endpoints of the Office 365 REST API.

https://<tenant>.sharepoint.com/_api/Web/GetAvailableWebTemplates(lcid=1033)?$filter=(IsHidden%20eq%20false)%20and%20(IsRootWebOnly%20eq%20false)

In this new request we specify that we don’t want to retrieve hidden templates (IsHidden = false) and templates available for the root site of a site collection (IsRootWebOnly = false).

When you execute the request, you will retrieve a list of desired templates with the following format for each of them.

{
    Description = "A place to work together with a group of people.",
    DisplayCategory = Collaboration,
    Id = 1,
    ImageUrl = "/_layouts/15/images/stts.png?rev=38",
    IsHidden = 0,
    IsRootWebOnly = 0,
    IsSubWebOnly = 0,
    Lcid = 1033,
    Name = "STS#0",
    Title = "Team Site"
}

To create a new site based on a specific template, you just have to get its name in the JSON response (e.g. STS#0 in the sample above).

Retrieve and use a digest token

You’re now able to submit a request with a well-formated HTTP body to create a new subsite but it’s not enough to work.

When you want to execute requests which perform create, update or delete operations, you have to retrieve a digest token and pass it to the HTTP headers of your request.

To retrieve a digest token, you have to submit an HTTP POST request to the following URL.

https://<tenant>.sharepoint.com/_api/ContextInfo

The response for this request is something like what you can see below.

{
    FormDigestTimeoutSeconds = 1800;
    FormDigestValue = "0x1234567890ABCDEF1234567890ABCDEF,14 Mar 2015 20:00:00 -0000";
    LibraryVersion = "16.0.3722.1239";
    SiteFullUrl = "https://<tenant>.sharepoint.com";
    SupportedSchemaVersions =     (
        "14.0.0.0",
        "15.0.0.0"
    );
    WebFullUrl = "https://<tenant>.sharepoint.com";
}

In this response, you have to extract the FormDigestValue, and pass it to your request in a HTTP header named X-RequestDigest.

By default, a digest is valid for 30 minutes (1800 seconds) but you can extract the FormDigestTimeoutSeconds value and add it to the current time to calculate the expiration date (better solution if Microsoft change the default duration in the future).

You’re now able to create a new subsite in a site collection by retrieving the list of available templates, by generating a digest token, and by submitting your creation request to SharePoint with the Office 365 REST API.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s