Introducing the IIS Administration API Monday, May 9, 2016

IIS is a mature technology with a large amount of configuration available. Historically the configuration of IIS has been done through WMI, Appcmd, PowerShell, and graphically through IIS Manager. All of these technologies have continued to serve their purpose, allowing users to configure the web server to meet their needs. Recently the IIS team has been working on a project to open up IIS configuration even more by creating a REST API that exposes the configuration system. This API is not meant to replace any of the existing configuration access mechanisms, but stand beside them and offer an open method for interacting with IIS. The REST API communicates with HTTPS making it accessible from any device that knows how to send a web request. This allows IIS to be configured more freely and opens the door for configuration clients that were not possible before, such as mobile applications.

Today we want to not only let everyone know that we are working on a REST API for IIS, we also want to let you see it. The API that we have created has a built in tool called the API Explorer that allows those with access to the API to browse the entire API surface. This means once you have a link to the root URL of the API you can navigate to this tool and browse all of the API that is available. Here is a picture of the API Explorer in action displaying an application pool resource.

Through this API Explorer you can browse the configuration resources of IIS such as authorization rules, modules, and applications. You can also delete these resources, modify them, and create new ones. We have deployed a read-only version of the API to a virtual machine in Azure to allow those who wish to explore the new API a chance to do so. The API available on this machine could be accessed via a simple HTTP client such as cURL, but for the first time experience we recommend giving the API Explorer a look to see what the tool has to offer.

Before connecting to this API let’s touch on the current authentication mechanisms that are in place to help keep it locked down. By default, the entire API is locked down with Windows authentication so that only administrators have access. This default behavior can be modified because, as is the case with many REST APIs available today, the Microsoft IIS Administration API mandates that an Access Token be sent with every request to the API. These access tokens can only be generated by Administrators on the machine that the API is installed on. In practice access tokens would be assigned to a specific user or group. For the purposes of the demo we have generated an access token for public use.

When initially connecting to the API Explorer you will see the following screen.

We have relaxed the requirement for windows authentication to connect to the demo API. This means the only authentication mechanism required is the access token. Once you input your access token into the input form and click connect you will have full access to the API in the API Explorer tool from your browser.

The API has been built with HAL (Hypertext Application Language). Utilizing HAL allows APIs to have built in discoverability. This is what the API Explorer leverages to create the clickable links that are seen. Through these links the whole API surface is available.

To access the API Explorer on the demo machine that we have deployed, visit https://jimmyca-srv2.cloudapp.net:55539. To connect to the API, you will need this demo access token: OgMks6N7CtZTptX2DTnLe8JvkmATOuqw1ZJnZzK1RojeYs251Wlfvg

Client examples

The API Explorer is perfect for discovering what is available from the service we are building. However, if we shift gears to other types of clients then we can demonstrate the power that we gain through the openness of a REST API. Here I give a couple of examples of how the new API allows unbiased interaction with IIS.

PowerShell

The following example uses built-in PowerShell commands to communicate with the IIS Administration API that is available on the public demo. Here we create a headers object that holds our access token for communicating with the API, then we make a request to the websites endpoint. Invoke-RestMethod returns a PowerShell object that is constructed from the JSON response returned from the API. To include HAL in the response object from the API, include the header 'Accept: application/hal+json'.

https://gist.github.com/jimmypc92/00ba9644b3966fc58a13dad80a5c7ef1

cURL

Using cURL, the same websites API endpoint can be accessed with the following command:

Note: The API that is hosted on the demo machine is using a self-signed certificate for encrypting HTTPS traffic. By default, cURL commands will reject communication with an untrusted certificate. This behavior is bypassed in the following command by passing the '–insecure' parameter.

curl --insecure https://jimmyca-srv2.cloudapp.net:55539/api/webserver/websites --header "Access-Token: Bearer OgMks6N7CtZTptX2DTnLe8JvkmATOuqw1ZJnZzK1RojeYs251Wlfvg" --header "Accept: application/json"

C# HttpClient

The following gist has an example utilizing the .NET HttpClient to communicate with the API.

https://gist.github.com/jimmypc92/254d5315b861ab53a9ba12033169f9e5