SPHttpClient class

SPHttpClient is used to perform REST calls against SharePoint. It adds default headers, manages the digest needed for writes, and collects telemetry that helps the service to monitor the performance of an application.

Remarks

This class is marked as @sealed. Subclasses should not extend it.

For communicating with other internet services, use the HttpClient class.

Constructors

(constructor)(serviceScope)

Constructs a new instance of the SPHttpClient class

Properties

configurations

The standard predefined SPHttpClientConfiguration objects for use with the SPHttpClient class.

serviceKey

The service key for SPHttpClient.

Methods

beginBatch(batchCreationOptions)

Begins an ODATA batch, which allows multiple REST queries to be bundled into a single web request.

fetch(url, configuration, options)

Perform a REST service call.

get(url, configuration, options)

Calls fetch(), but sets the method to "GET".

getWebUrlFromRequestUrl(requestUrl)

Use a heuristic to infer the base URL for authentication.

post(url, configuration, options)

Calls fetch(), but sets the method to "POST".

Constructor Details

(constructor)(serviceScope)

Constructs a new instance of the SPHttpClient class

constructor(serviceScope: ServiceScope);

Parameters

serviceScope
ServiceScope

Property Details

configurations

The standard predefined SPHttpClientConfiguration objects for use with the SPHttpClient class.

static readonly configurations: ISPHttpClientConfigurations;

Property Value

serviceKey

The service key for SPHttpClient.

static readonly serviceKey: ServiceKey<SPHttpClient>;

Property Value

ServiceKey<HttpClientConfiguration>

Method Details

beginBatch(batchCreationOptions)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Begins an ODATA batch, which allows multiple REST queries to be bundled into a single web request.

beginBatch(batchCreationOptions?: ISPHttpClientBatchCreationOptions): SPHttpClientBatch;

Parameters

batchCreationOptions
ISPHttpClientBatchCreationOptions

Returns

HttpClientConfiguration

An SPHttpClientBatch object used to manage the batch operation.

fetch(url, configuration, options)

Perform a REST service call.

fetch(url: string, configuration: SPHttpClientConfiguration, options: ISPHttpClientOptions): Promise<SPHttpClientResponse>;

Parameters

url

string

the URL to fetch

configuration
HttpClientConfiguration

determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations

options
ISPHttpClientOptions

additional options that affect the request

Returns

!Promise:class<HttpClientConfiguration>

A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.

Remarks

Generally, the parameters and semantics for SPHttpClient.fetch() are essentially the same as the WHATWG API standard that is documented here: https://fetch.spec.whatwg.org/

The SPHttpClient subclass adds some additional behaviors that are convenient when working with SharePoint ODATA API's (which can be avoided by using HttpClient instead):

  • Default "Accept" and "Content-Type" headers are added if not explicitly specified.

  • For write operations, an "X-RequestDigest" header is automatically added

  • The request digest token is automatically fetched and stored in a cache, with support for preloading

For a write operation, SPHttpClient will automatically add the "X-RequestDigest" header, which may need to be obtained by issuing a separate request such as "https://example.com/sites/sample/_api/contextinfo". Typically the appropriate SPWeb URL can be guessed by looking for a reserved URL segment such as "_api" in the original URL passed to fetch(); if not, use ISPHttpClientOptions.webUrl to specify it explicitly.

get(url, configuration, options)

Calls fetch(), but sets the method to "GET".

get(url: string, configuration: SPHttpClientConfiguration, options?: ISPHttpClientOptions): Promise<SPHttpClientResponse>;

Parameters

url

string

the URL to fetch

configuration
HttpClientConfiguration

determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations

options
ISPHttpClientOptions

additional options that affect the request

Returns

!Promise:class<HttpClientConfiguration>

A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.

getWebUrlFromRequestUrl(requestUrl)

Use a heuristic to infer the base URL for authentication.

static getWebUrlFromRequestUrl(requestUrl: string): string;

Parameters

requestUrl

string

The URL for a SharePoint REST service

Returns

string

the inferred SPWeb URL

Remarks

Attempts to infer the SPWeb URL associated with the provided REST URL, by looking for common SharePoint path components such as "_api", "_layouts", or "_vit_bin". This is necessary for operations such as the X-RequestDigest and ODATA batching, which require POSTing to a separate REST endpoint in order to complete a request.

For example, if the requestUrl is "/sites/site/web/_api/service", the returned URL would be "/sites/site/web". Or if the requestUrl is "http://example.com/_layouts/service", the returned URL would be "http://example.com".

If the URL cannot be determined, an exception is thrown.

post(url, configuration, options)

Calls fetch(), but sets the method to "POST".

post(url: string, configuration: SPHttpClientConfiguration, options: ISPHttpClientOptions): Promise<SPHttpClientResponse>;

Parameters

url

string

the URL to fetch

configuration
HttpClientConfiguration

determines the default behavior of SPHttpClient; normally this should be the latest version number from SPHttpClientConfigurations

options
ISPHttpClientOptions

additional options that affect the request

Returns

!Promise:class<HttpClientConfiguration>

A promise with behavior similar to WHATWG fetch(). This promise will resolve normally (with HttpClientResponse.ok being false) for error status codes such as HTTP 404 or 500. The promise will only reject for network failures or other errors that prevent communication with the server.