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 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 |
|---|---|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
Related topics
Other resources
Handling exceptions in network apps
How to configure network isolation capabilities
How to enable loopback and debug network isolation
Reference
Samples
Integrating content and controls from web services sample