Web requests overview

This topic provides an overview of Hypertext Transfer Protocol (HTTP) and WebSocket web requests for Microsoft Game Development Kit (GDK) titles.

Starting with the right API set makes it easier for you to implement secure communication that is compliant with Xbox Requirements (XRs).

Xbox consoles and Windows 10 PCs

We recommend the use of the following APIs to adhere to security requirements. They also help simplify the implementation of web requests.

Use case	Recommended API
REST requests with Gaming Runtime Services (GRTS) style APIs	Microsoft Xbox Live Service API (XSAPI)
General purpose HTTP requests	xCurl
WebSocket requests	libHttpClient

Windows HTTP Services (WinHTTP)

WinHTTP can also be used to create HTTP and WebSocket service endpoints on both PCs and Xbox consoles with no code changes. Because this API does not automatically handle all security best practices, make sure to read Communication Security Overview (NDA topic)Authorization required and WinHTTP overview to learn how to ensure that your implementation is secure and robust.

The advantage of xCurl is that it handles security best practices, including certificate chain validation, and networking connectivity checks. This is the reason why we recommend xCurl for general purpose HTTP requests.

NOTE:

• When developing titles for Xbox consoles, you must use WinHTTP or xCurl. Custom HTTP stack implementations are not allowed. For more information, see XR-134: Data Transfer Using Web Protocols under Security in Xbox Requirements for Xbox Console Games.
• When developing titles for PCs, there are more options. For general purpose HTTP requests, you can also use libCurl or any other HTTP stack directly with your Microsoft Game Development Kit (GDK) title.

xCurl

xCurl is the recommended API for HTTP requests in Microsoft Game Development Kit (GDK) titles. It simplifies title development by adhering to all security best practices automatically. Since the API surface broadly matches libCurl, it also has libCurl's full flexibility and HTTP feature set.

To learn more about the xCurl API and differences between xCurl and libCurl, see xCurl overview.

XSAPI

Xbox Services API (XSAPI) provides a generic REST wrapper that's fully compliant for Microsoft Game Development Kit (GDK) titles. This wrapper is straightforward to use and follows the Microsoft Game Development Kit (GDK) asynchronous API model. If your title only needs to make REST HTTP requests, this is likely the simplest fully compliant interface to use.

1. Use XblHttpCallCreate to create an HTTP handle to track your REST request.
2. Fill in the body and any additional configuration with one of the XblHttpCallRequestSet* functions.
3. Call XblHttpCallPerformAsync to make the request.
4. To retrieve the response, use one of the XblHttpCallGet* functions.
5. Close the handle by using XblHttpCallCloseHandle.

Note

XblHttpCallRequestSet* and XblHttpCallGet* represent groups of functions to build HTTP requests and retrieve HTTP responses.

• XblHttpCallRequestSetHeader

• XblHttpCallRequestSetLongHttpCall

• XblHttpCallRequestSetRequestBodyBytes

• XblHttpCallRequestSetRequestBodyString

• XblHttpCallRequestSetRetryAllowed

• XblHttpCallRequestSetRetryCacheId

• XblHttpCallGetHeader

• XblHttpCallGetHeaderAtIndex

• XblHttpCallGetNetworkErrorCode

• XblHttpCallGetNumHeaders

• XblHttpCallGetPlatformNetworkErrorMessage

• XblHttpCallGetRequestUrl

• XblHttpCallGetResponseBodyBytes

• XblHttpCallGetResponseBodyBytesSize

• XblHttpCallGetResponseString

• XblHttpCallGetStatusCode

libHttpClient

The libHttpClient is designed enable two-way communication. It is an abstraction layer designed for use by Xbox Live Service API (XSAPI) to enable HTTP and WebSocket service endpoints. The API is in the Game Development Kit (GDK) as part of XSAPI.

See also

Windows HTTP Services (WinHTTP)

libcurl

Setting up web services at Partner Center (NDA topic)Authorization required

Fiddler on Xbox One consoles

Communication Security Overview (NDA topic)Authorization required