Working with the Web Service Interface

Windows HPC Server 2008 R2 with Service Pack 2 (SP2) provides access to the HPC Job Scheduler Service by using an HTTP web service that is based on the representational state transfer (REST) model. You can use this REST API to create client applications that users can use to define, submit, modify, list, view, requeue, and cancel jobs.

Windows HPC Server 2008 R2 with Service Pack 3(SP3) expands the HTTP web service to provide additional operations that provide information about nodes, node groups, and the cluster name. Windows HPC Server 2008 R2 with SP3 also provides operations that allow you to create and manage SOA sessions, and to send SOA requests and receive SOA responses for these sessions. The SOA operations that are available only when the REST web service is hosted in Windows Azure. All other operations are available either when the REST web service is hosted on an on-premise cluster or when the REST web service is hosted in Windows Azure.

You can use the REST API in many programming languages to create client applications, including programming languages that the .NET and COM APIs for Windows HPC Server do not support. You can also use to the REST API to create client applications that users on many operating systems can access, including operating systems that are not Windows-based.

Installing and Configuring the REST API

The web service is included in the HPC Pack web features installation package.

To install the HPC web features

1. In Windows Explorer on the head node of your HPC cluster, navigate to the Setup folder on the installation media for the Microsoft HPC Pack 2008 R2 with SP2, or open the folder that you extracted from the download if you downloaded the SP2 update from the Microsoft Download Center.
2. Double-click HpcWebComponents.msi.
3. Follow the instructions in the Microsoft HPC Pack 2008 R2 Web Components Setup wizard.

You can use the Set-HPCWebComponents.ps1 script to configure the REST API after you install the REST API. For example, you can use the script to change the port or the method to authenticate client credentials that the REST API uses. This script is located in the %CCP_HOME%\bin folder on the head node after you install the HPC web features.

The following example shows the syntax for the Set-HPCWebComponents.ps1 script.

Set-HPCWebComponent.ps1 -Service service_name -enable -Certificate thumbprint_value [-Port port_number] [-AuthenticationMethod method_name]

Set-HPCWebComponent.ps1 -Service service_name -disable 

The following table describes the parameters for the Set-HPCWebComponents.ps1 script.

The following example turns on the REST web service for port 8000 with NTLM authentication.

Set-HPCWebComponents -Service REST -enable -Certificate 33CE10B55FE9A657815C3B19791340E375B7DF7C -AuthenticationMethod NTLM -Port 8000

The following example turns off the REST web service.

Set-HPCWebComponents.ps1 -Service REST -disable

Operations in the REST API

The HPC REST API defines a number of operations that you can perform, including the information that is expected in the HTTP requests that you send to the HPC REST web service and that is provided in the HTTP responses that you receive in return as part of each operation.

Note  

The HPC REST API does not define the manner in which you create and send these HTTP requests and process the HTTP responses. The approach you can use to work with the HTTP requests and responses varies depending on the programming language that you use, and can also vary depending on the libraries or other tools that you choose to install to work with HTTP requests and responses in your programming language of choice. Additional information about working with the HTTP requests and responses is beyond the scope of this documentation. For an example of how to HTTP requests and responses for operations in the HPC REST API, see Creating and Submitting Jobs by Using the REST API in Windows HPC Server 2008 R2. (http://social.technet.microsoft.com/wiki/contents/articles/7737.creating-and-submitting-jobs-by-using-the-rest-api-in-windows-hpc-server-2008-r2.aspx)

The following table shows the operations that are available in the REST API both when the REST web service is hosted in an on-premise cluster, and when the REST web service is hosted in Windows Azure.

The following table shows the operations that are available only when the REST web service is hosted in Windows Azure. All of the operations are supported starting with Windows HPC Server 2008 R2 with SP3.

Getting Sample Programs that use the REST API

The SDK code samples for include sample client applications that use the REST API.

The code samples for Windows HPC Server 2008 R2 with SP2 include sample client applications in C# and Python that use the operations related to jobs and tasks. The code samples for Windows HPC Server 2008 R2 with SP3 include updated versions of these C# and Python applications, and additional sample client applications in C and Java that use the SOA operations.

You can download the SDK code samples for Windows HPC Server 2008 R2 with SP2 by downloading the HPC2008R2.SampleCode.zip file from the HPC Pack 2008 R2 SDK with Service Pack 2 download page (http://www.microsoft.com/download/en/details.aspx?id=26645). After you extract the files, the REST API examples are in the HPC2008R2.SampleCode\Scheduler\REST folder.

For Windows HPC Server 2008 R2 with SP2, the C# example requires that you install the WCF REST Starter Kit Preview 2. For information about how to download the WCF REST Starter Kit Preview 2, see http://aspnet.codeplex.com/releases/view/24644.

You can download the SDK code samples for Windows HPC Server 2008 R2 with SP3 by downloading the HPC2008R2.SampleCode.zip file from the HPC Pack 2008 R2 SDK with Service Pack 3 download page (http://www.microsoft.com/download/en/details.aspx?id=28016). After you extract the files, the C# and Python examples are in the HPC2008R2.SampleCode\Scheduler\REST folder. The C example is in the HPC2008R2.SampleCode\SOA\CPP\SoaWebApiClient folder. The Java example is in the HPC2008R2.SampleCode\SOA\Java\SoaWebApiClient folder.

For Windows HPC Server 2008 R2 with SP3, the C# example no longer requires that you install the WCF REST Starter Kit Preview 2. The C example requires the CURL and json-c libraries. For information about these libraries, see http://curl.haxx.se and http://oss.metaparadigm.com/json-c.

Build date: 7/27/2012