Share via


Connecting to web services (HTML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

These topics demonstrate various methods to connect to a web service in a Windows Runtime app. The recommended method is to use Windows.Web.Http.HttpClient, a new Windows Runtime class available for all languages. This is the most full-featured and powerful API an app can use to access a web service.

Classes in the Windows.Web.Http namespace provide a programming interface for modern HTTP client apps. The Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces provide HTTP client components that allow users to make HTTP requests and receive HTTP responses from modern web services over HTTP.

For basic HTTP request operations, the Windows.Web.Http.HttpClient has a simple interface to handle the most common tasks and provides sensible defaults for authentication (AUTH) that apply to most scenarios. For more complex HTTP operations, many additional capabilities are available.

The topics in this section also discuss a Windows Library for JavaScript wrapper for XMLHttpRequest called WinJS.xhr. WinJS.xhr that provides an easy way to access web content in your app. You can use WinJS.xhr to make HTTP or HTTPS requests to download or upload content and files of any format.

Unlike XMLHttpRequest, which allows you to specify whether the request should be made asynchronously, WinJS.xhr is always asynchronous. WinJS.xhr returns a WinJS.Promise, so that you can handle completed requests, errors, and in-progress requests by using the then or done methods.

Warning  It is now possible to use XMLHttpRequest to transfer extremely large objects, such as Blob objects and FormData objects, which might take a long time to complete. Windows.Web.Http.HttpClient can also be used to send or receive extremely large objects including streams. Because an app can be terminated at any time, you should consider using the background transfer in the Windows.Networking.BackgroundTransfer namespace for these operations. For more info about uploading and downloading large content, see How to Upload a file and Transferring data in the background.

 

The following table lists APIs that can be used to access a web service by apps written in JavaScript. The Platform indicates the version of Windows where the feature was first added.

API Platform Comments

Windows.Web.Http.HttpClient

Windows 8.1, Windows Phone 8.1, Windows Server 2012 R2

This is the recommended method to connect to a HTTP server to send and receive data.

This feature is also supported in apps written in JavaScript, C#, Visual Basic, and C++

WinJS.xhr Windows 8, Windows Phone 8.1, Windows Server 2012,

On Windows 8 and Windows Server 2012, this was the recommended method when XMLHttpRequest was not adequate.

XMLHttpRequest Windows 8, Windows Phone 8.1, Windows Server 2012 This object and API is available in JavaScript implementations on most modern web browsers.

 

Developer Audience

Developers using JavaScript and HTML interested in creating apps that connect to a web service.

The information in this topic applies to apps written in JavaScript and HTML.

For more information on how to connect to a web service for apps written in C++/XAML and apps using the .NET Framework 4.5 and written in C# or Visual Basic, see Connecting to web services (XAML).

In this section

Topic Description

How to connect to an HTTP server using Windows.Web.Http

Send a GET request to a web service and retrieve the response using the Windows.Web.Http.HttpClient class in the Windows.Web.Http namespace.

How to require an HTTPS connection

With the "ms-https-connections-only" meta element value you can prevent your app from using HTTP connections for navigation or other non-media web content retrievals. When you set this meta element's content attribute to "true", HTTP navigation and non-media web content retrievals will fail.

How to download a file with WinJS.xhr

WinJS.xhr provides an easy way to download web content in your app. This topic shows how to download a file using WinJS.xhr, handle any errors, and report on the progress of the download. It also shows how to download different types of content.

How to upload binary data with WinJS.xhr

You can upload and download binary data when you use WinJS.xhr (which wraps XMLHttpRequest). This example shows how to upload a bitmap from your Pictures. The Windows Runtime method that is used to open the bitmap file returns an IRandomAccessStream, so you must use MSApp.createBlobFromRandomAccessStream to convert it to a Blob.

Warning  You can now use XMLHttpRequest to upload or download objects that are larger than a few MB, such as Blob objects and FormData objects, which may take a long time to complete. Because apps can be terminated at any time, you should consider using the Windows Runtime background transfer APIs for these operations. For more information about uploading and downloading content, see How to upload a file and How to download a file. For a general discussion of background transfer, see Transferring data in the background.
 

How to ensure that WinJS.xhr resends requests

When you request Web resources by using WinJS.xhr, the response might be cached, which means that later requests will return the version of the resource that already exists on the client computer rather than resending the request. However, you can add an HTTP header that ensures that the request is sent again, even if it has already been cached.

Setting timeout values with WinJS.xhr or HttpClient

When you use XMLHttpRequest, you can set time-out values directly, but you cannot do this when you use Windows.Web.Http.HttpClient or WinJS.xhr. However, there is a way to set time-outs on WinJS.Promise objects. By calling WinJS.Promise.timeout, you ensure that the request is canceled if it has not completed within the specified time.

How to create a mashup using WinJS.xhr

A mashup is a web application that uses data from two or more sources to create something new. This example shows you how to use XMLHttpRequest (XHR) to retrieve and display a remote Really Simple Syndication (RSS) feed.

 

Other resources

App capability declarations

Handling exceptions in network apps

How to configure network isolation capabilities

How to enable loopback and debug network isolation

Reference

Windows.Foundation.Uri

Windows.Web.Http

Windows.Web.Http.Filters

Windows.Web.Http.Headers

Windows.Web.Http.HttpClient

WinJS.xhr

XMLHttpRequest

Samples

HttpClient Sample

Integrating content and controls from web services sample

Using a Blob to save and load content sample

Web authentication sample

XHR, handling navigation errors, and URL schemes sample