Tell us about your PDF experience.

Introduction to the Microsoft IIS

Administration API
Article • 07/25/2022

The Microsoft IIS Administration API is a REST API that enables consumers to configure
and monitor their IIS web servers. With the API installed on an IIS machine, one can
configure an IIS instance with any HTTP client.

Why Use IIS Administration?

There are many methods available to configure IIS including appcmd.exe, PowerShell,
and .NET. These methods have their benefits, but one thing they lack is an open and
standard interface. The IIS Administration API builds upon the principles of REST APIs to
provide an interface that can be consumed regardless of platform. This is the ultimate
way to open up IIS to any client. There are few frameworks today that don't provide
HTTP support, and most frameworks provide methods to simplify communicating with
REST APIs. Powerful scripts can be made from a myriad of clients such as PowerShell,
cURL, and Python just by performing HTTP requests with JSON payloads.

IIS Administration is the perfect option for remote management. The API is a micro
service that runs on the target machine, so by nature it is meant to serve remote
requests. Opening up the port that the service listens on is the only step necessary to
make remote management available for the machine. This means, web site creation,
application pool monitoring, and security configuration can be handled from one client
for a cluster of machines with little overhead.

The IIS Administration service is being developed to completely open up IIS. There are
constantly features being worked on and added. We are able to release updates quickly
because the Administration Service is a separate download from the IIS service. This also
has means that customers can depend on whichever version of the API that they choose.

Security is a top priority. Our service can use any form of authentication and
authorization that IIS uses. This means client certificate authentication, basic
authentication, and even Windows authentication. Every call made to the API requires an
access token in the request header and the service is not available from outside of the
machine unless the port that it listens on is opened. The built-in security allows users to
confidently install the IIS Administration API on their machines without worrying that
they are compromising their system.
So Many Options
A REST API is accessible from anywhere.

PowerShell
.NET
Java
Python
Javascript
Native mobile applications (Android, iOS, Windows)
Browser applications

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Getting started
Article • 07/25/2022

Requirements
The Microsoft IIS Administration API supports Windows 7 and above.

The IIS Administration API depends on .NET Core and will automatically download and
install it if it is not present on the machine

Microsoft .NET Core

Installing
The latest version of the Microsoft IIS Administration API is available for download
here .

After installation is a perfect time to configure the service for its intended purpose. To
get a better idea of what the API has to offer, take a look at the built-in API explorer.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Application Settings (appsettings.json)
Article • 07/25/2022

All of the application's settings are contained in a file named appsettings.json. Any
changes to the appsettings.json file will require restarting the "Microsoft IIS
Administration" service to take effect.

The appsettings.json file is located at: %SystemDrive%\Program Files\IIS Administration\

<version>\Microsoft.IIS.Administration\config\appsettings.json

CORS
CORS policies allow browser based applications to send requests to the Microsoft IIS
Administration API.

Default Settings
The IIS Administration API will not allow CORS for any origin if there are no cors settings
present.

Format
For example, the following setting enables CORS:

"cors": {
"rules": [
{
"origin": "https://contoso.com",
"allow": true
}
]
}

rules: A set of CORS rules to control how the API shares resources.

origin: The origin, as defined in the CORS specification, to allow or deny. If the
wild card character, *, is provided as the origin, that rule will apply to all origins.

allow: Indicates whether resources should be shared to the specified origin.

Files
Multiple endpoints require interacting with the file system, such as creating a web site in
an existing directory (read) or uploading the content of a file (write). These configuration
settings provide a method to restrict these file system interactions. A set of file system
locations that are visible to the API are specified. These paths can have read and or write
priveleges associated with them.

Default Settings
The IIS Administration API will allow read access to %systemdrive%\inetpub if there are
no files settings present.

Format
The following settings allow read/write access to %systemdrive%\inetpub

"files": {
"locations": [
{
"alias": "inetpub",
"path": "%systemdrive%\\inetpub",
"claims": [
"read",
"write"
]
}
]
}

skip_resolving_symbolic_links: A flag specifying whether the system will resolve

symbolic links when determining whether a path is allowed. By default this flag is false,
meaning symbolic links will be resolved.

locations: A set of file system locations and associated rights specifying what operations
are allowed to be performed through the API.

alias: A name for the location.

path: A root path to assign the list of claims. All files or directories under this path
inherit the list of claims unless overridden with a more specific path.
 claims: Specifies what operations are allowed to be performed on files directories
under the path. An empty set of claims means no access will be allowed to that
location.

Security
The security section was introduced in IIS Administration 2.0.0. This section specifies the
requirements to access the API.

Default Settings
By default the API requires all requests to have valid Windows credentials as indicated
by the require_windows_authentication flag. Access to the API's resources, such as
websites and applications, and access key manipulation require the user to be in the
administrators API role. High privilege operations require the user to be in the owners
role. When the API is installed, the administrators and owners roles are automatically
populated with the user that executed the installer.

Format

"security": {
"require_windows_authentication": true,
"users": {
"administrators": [
],
"owners": [
]
},
"access_policy": {
"api": {
"users": "administrators",
"access_key": true
},
"api_keys": {
"users": "administrators",
"access_key": false
},
"system": {
"users": "owners",
"access_key": true
}
}
}
require_windows_authentication: A boolean value that specifies whether valid Windows
authentication is required for all requests to the API. If true, any request that is not
Windows authenticated will be rejected. If false, Windows authentication requirements
are determined by the access_policy settings.

users: A mapping between Windows users/groups and roles within the API. Any role can
be added, but by default the appsettings.json file contains administrators and owners.
These roles are used in the access_policy section to govern access to different sections of
the API.

access_policy: Access policies specify a set of requirements to access areas within the
API. The IIS Administration API comes with three different access policies, api, api_keys,
and system.

api: This access policy is for API resources such as web sites, application pools, and
files.

api_keys: This access policy is for manipulating API keys.

system: This access policy is for high privilege actions that are offered by the API,
such as changing the identity of an application pool to LocalSystem.

Each access policy has a set of requirements that can be configured. The available
requirements are:

users: Specifies which roles from the security.users section are allowed access. To allow
all users use a value of 'Everyone'.

access_key: Specifies whether requests are required to have an access token.

read_only: Enforces a read-only mode by restricting all requests to use the HTTP GET
method.

forbidden: Blocks all access.

Complete Example

{
"host_id": "",

"host_name": "My instance of the IIS Administration API",

"logging": {
"enabled": true,
 "file_name": "log-{Date}.txt",
"min_level": "Error",
"path": null
},

"auditing": {
"enabled": true,
"file_name": "audit-{Date}.txt",
"path": null
},

"security": {
"require_windows_authentication": true,
"users": {
"administrators": [
],
"owners": [
]
},
"access_policy": {
"api": {
"users": "administrators",
"access_key": true
},
"api_keys": {
"users": "administrators",
"access_key": false
},
"system": {
"users": "owners",
"access_key": true
}
}
},

"cors": {
"rules": [
{
"origin": "https://contoso.com",
"allow": true
}
]
},

"files": {
"locations": [
{
"alias": "inetpub",
"path": "%systemdrive%\\inetpub",
"claims": [
"read"
]
}
]
 }
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Access Tokens
Article • 07/26/2019

Every request to the API requires an access token. If a request is made to the API
without an access token, the API will respond with an HTTP 403 status code and will set
the 'WWW-Authenticate' HTTP header to 'Bearer'. The API expects the access token to
be in the Access-Token header of every request. The value of the Access-Token header
should be 'Bearer ' followed by the access token being used to access the API.

GET /api
Access-Token: Bearer {Access-Token}

Generating Tokens
Access tokens can be generated in multiple ways. The predominant method is through
the built in API Explorer. Access tokens can also be generated programatically through
the API keys endpoint.

Generating Tokens Through The API Explorer

The API explorer has an "ACCESS KEYS" link at the top right. Clicking this link will lead to
the access token management page. Here access tokens can be generated, deleted, and
refreshed. Access tokens should be created with a descriptive purpose and one access
token should be created for one user.
Alternatively, the API offers a method to programatically generate API keys.

Securing Tokens
By default only members of the 'Administrators' and 'IIS Administrators' can generate
access tokens. This requirement is set through the integrated security that the IIS
Administration API utilizes. Windows Authentication provides more information on the
integrated security used by the API.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Web.Config
Article • 07/25/2022

This article is deprecated as of IIS Administration 2.0.0. and has been replaced by the
appsettings security section

The Microsoft IIS Administration API has access to all of the integrated security
mechanisms offered by IIS. These settings are located in the web.config file that comes
with the installation of the API. In this file windows authentication and authorization
requirements are specified. This file can be manipulated to customize who is allowed to
access the API, for example, windows authentication can be replaced with client
certificate authentication. Any changes to the web.config file will require restarting the
"Microsoft IIS Administration" service to take effect.

The web.config file is located at: IIS Administration\

<version>\Microsoft.IIS.Administration\web.config

Default Settings

<?xml version="1.0" encoding="utf-8"?>

<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule"
resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\Microsoft.IIS.Administration.dll"
forwardWindowsAuthToken="true" stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
<security>
<authentication>
<windowsAuthentication enabled="true" />
</authentication>
<authorization>
<clear />
<add accessType="Allow" roles="Administrators,IIS Administrators" />
</authorization>
</security>
</system.webServer>
<!--
ALWAYS PROTECTED SECURITY AREA
THE HOST MUST PROVIDE AUTHENTICATION

[Windows Authentication]
 [Client Certificate Authentication]
-->
<location path="security">
<system.webServer>
<security>
<authentication>
<anonymousAuthentication enabled="false" />
<windowsAuthentication enabled="true" />
</authentication>
<authorization>
<clear />
<add accessType="Deny" users="?" />
<add accessType="Allow" roles="Administrators,IIS Administrators"
/>
</authorization>
</security>
</system.webServer>
</location>
<!--
API area
Protected by ACCESS TOKEN
The host can provide additional authentication on top
-->
<location path="api">
<system.webServer>
<security>
<authentication>
<!-- Need for CORs -->
<anonymousAuthentication enabled="true" />
</authentication>
<authorization>
<!-- Need for CORs -->
<add accessType="Allow" verbs="OPTIONS" users="*" />
</authorization>
</security>
</system.webServer>
</location>
</configuration>

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Windows Authentication
Article • 01/24/2019

This article is deprecated as of IIS Administration 2.0.0. and has been replaced by the
appsettings security section

Out of the box, the Microsoft IIS Administration API utilizes IIS's windows authentication
module to authenticate users. These settings are specified in the web.config file. The
windows authentication module restricts access to the API to to users in the
Administrators and IIS Administrators groups. By manipulating the web.config file, one
can alter the requirements for windows authentication. If windows authentication is
removed access tokens become the sole mechanism for security.

Browser Access
Depending on browser settings, users who access the API via the built-in API Explorer
may notice a login prompt. This is the browser's mechanism for authenticating with
windows credentials. Domain users should include their domain name when specifying
their username, for example contoso\johndoe.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Authorization
Article • 07/26/2019

This article is deprecated as of IIS Administration 2.0.0. and has been replaced by the
appsettings security section

By default the Microsoft IIS Administration API only allows access to windows users that
are part of the Administrators and IIS Administrators groups. The IIS Administrators
group is generated during installation of the API and the installing user is automatically
added to the group.

Route Based Authorization

/security
The /security route is security critical, therefore the web.config file specifies the security
settings for this route separately. It is recommended not to lift the requirement for users
to be in the Administrators or IIS Administrators group to access this route.

This route is used for generating access tokens.

/api
On top of the default authorization requirements, the /api route requires an access-
token with every request. Some users may wish to modify the windows based
authorization requirements of the api route to add or remove roles. This is a viable
option for those wishing to use the API to administor their servers.

The /api route allows anonymous access for HTTP OPTIONS requests. This is necessary
for CORS requests from allowed origins to be successful. Without this rule, browser
based GUIs would not be capable of using the API.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

API Explorer
Article • 06/28/2019

The Microsoft IIS Administration API comes with a built in interface called the API
Explorer. This explorer allows users to navigate the API using hyperlinks. Resources can
be created, retrieved, modified, and removed directly from this tool. By default, the API
Explorer can be reached by browsing https://localhost:55539 on any machine that has
the API installed. This interface is also where access tokens are created.

Connecting
The first time that the api explorer is used it will prompt for an access token. Every
request to the API requires an access token, even those made from the explorer. Input
the access token that you use to communicate with the API or click on the "ACCESS
KEYS" link at the top right of the explorer to generate an access token. Checking the
"Keep me connected" box will allow your browser to remember your access token for
future use of the explorer.

Browsing
Once you have connected to the explorer you can begin browsing. The API's resources
have been designed using HAL , which allows the resources to provide the navigation
engine used by the explorer. As links are clicked the url in the nagivation pane at the top
of the explorer is updated to reflect the location of the current resource.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Interacting with Resources
Article • 01/24/2019

The API Explorer enables resources to be retrieved, updated, created and deleted. The
type of interaction is specified by the methods at the top of the navigation panel.

METHOD DESCRIPTION

GET Retrieves the specified resource

POST Creates a resource

PATCH Updates the specified resource

DELETE Deletes the specified resource

HEAD Similar to get except only returns HTTP headers

Creating a Resource
By selecting the post option on the navigation panel, resources can be created. When
the post option is selected a text area appears on the screen where the JSON
representation of a resource can be written. The JSON in this text area is used to create
the resource when the go arrow is clicked.
Updating a Resource
The modification of resources is done by issuing patch requests. To update a resource,
select the patch option on the navigation pane which will open the text area for the
request content. The content of the patch request should contain the desired state of
the resource. For example, to stop a web site we send a patch request indicating that
the status of the web site should be stopped.

Before Patch Request

After Patch Request

Here we see that after a successful patch request the resource reflects the state that we
specified.
Deleting a Resource
To delete a resource, first navigate to the target resource in the api explorer. Then select
the delete method on the navigation panel and press the go button.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Connecting to the Management Portal
Article • 01/24/2019

The web based manager at manage.iis.net is the perfect way to administer IIS
machines. The web manager can be used to connect to multiple servers whether they be
local or remote. The portal can even be used to download and install the API if it is not
already present on the local machine.

Initial Visit
When visiting the management portal for the first time, a welcome page will appear
allowing the API to be downloaded. The download button contains the latest release of
the IIS Administration API. Once the installer has been downloaded the management
portal will wait for the installation to finish. To skip installation of the API and go straight
to the connect screen click the Skip this button.
Connecting
When the installation has completed successfully the connect screen will appear. From
this screen, connections can be made to any IIS server that is running the administration
API. To finish connecting to the local instance of the API, an access token must be
acquired. After generating an access token, return to the connect screen and paste the
access token into the Access Token field. Click connect to finish creating the connection
to the API.
Acquiring an Access Token
Clicking the "Get Access Token" link under the Access Token field will open up the access
tokens page of the API explorer. Once at the access key creation screen, create a key to
enable access to the API from the management portal. When an access key is generated
the expiration time of the key can be set and a purpose can be provided. A good
purpose will tell the reader who the key belongs to, where it is being used, and how it is
being used. The creation of an access key will display an associated access token. This is
the private value that is used on the GUI connection screen and it should not be shared.
Connect
When the access token has been provided in the access token field, the connect button
will light up. Check the remember me box if using a trusted machine to make the
management experience better on subsequent accesses. Otherwise the access token will
have to be input again. Click the connect button to move to the homepage of the web
manager.

Changing the Current connection

If the remember me box is checked when making a connection then the connection is
saved. The active connection can be changed at any time by clicking the connection
menu at the top left. The connection menu lists all the saved connections. It can also be
used to edit or delete an existing connection. Select the connection out of the menu to
make it the active connection.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Application Pool Resource
Article • 01/24/2019

Application pools provide an isolation mechanism for processes on the web server.
There are many different settings available to fine-tune the behavior of the worker
processes used to serve request through IIS. The application pool API allows consumers
to create, read, delete, or update their application pools.

GET /api/webserver/application-pools/{id}

{
"name": "DefaultAppPool",
"id": "{id}",
"status": "started",
"auto_start": "true",
"pipeline_mode": "integrated",
"managed_runtime_version": "v4.0",
"enable_32bit_win64": "false",
"queue_length": "1000",
"cpu": {
"limit": "0",
"limit_interval": "5",
"action": "NoAction",
"processor_affinity_enabled": "false",
"processor_affinity_mask32": "0xFFFFFFFF",
"processor_affinity_mask64": "0xFFFFFFFF"
},
"process_model": {
"idle_timeout": "20",
"max_processes": "1",
"pinging_enabled": "true",
"ping_interval": "30",
"ping_response_time": "90",
"shutdown_time_limit": "90",
"startup_time_limit": "90",
"idle_timeout_action": "Terminate"
},
"identity": {
"identity_type": "ApplicationPoolIdentity",
"username": "",
"load_user_profile": "true"
},
"recycling": {
"disable_overlapped_recycle": "false",
"disable_recycle_on_config_change": "false",
"log_events": {
"time": "true",
"requests": "true",
 "schedule": "true",
"memory": "true",
"isapi_unhealthy": "true",
"on_demand": "true",
"config_change": "true",
"private_memory": "true"
},
"periodic_restart": {
"time_interval": "1740",
"private_memory": "0",
"request_limit": "0",
"virtual_memory": "0",
"schedule": []
}
},
"rapid_fail_protection": {
"enabled": "true",
"load_balancer_capabilities": "HttpLevel",
"interval": "5",
"max_crashes": "5",
"auto_shutdown_exe": "",
"auto_shutdown_params": ""
},
"process_orphaning": {
"enabled": "false",
"orphan_action_exe": "",
"orphan_action_params": ""
},
"_links": {
"webapps": {
"href": "/api/webserver/webapps?application_pool.id={id}"
},
"websites": {
"href": "/api/webserver/websites?application_pool.id={id}"
},
"worker_processes": {
"href": "/api/webserver/worker-processes?application_pool.id=
{id}"
}
}
}

Creating an Application pool

The only information required to create an application pool is a name.

Creating an application pool. POST /api/application-pools

 {
"name": "Demonstration App Pool"
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Web Site Resource
Article • 07/26/2019

Web sites are a core entity of IIS that determine where and how requests will be
handled. The web site API allows consumers to create, read, delete, or update their web
sites. This is suitable for scripting automated deployments or making alterations to
existing resources.

GET /api/webserver/websites/{id}

{
"name": "Default Web Site",
"id": "{id}",
"physical_path": "%SystemDrive%\\inetpub\\wwwroot",
"key": "1",
"status": "started",
"server_auto_start": "true",
"enabled_protocols": "http",
"limits": {
"connection_timeout": "120",
"max_bandwidth": "4294967295",
"max_connections": "4294967295",
"max_url_segments": "32"
},
"bindings": [
{
"protocol": "https",
"binding_information": "*:443:",
"ip_address": "*",
"port": "443",
"hostname": "",
"certificate": {
"name": "Web Hosting Certificate",
"id": "{certificate_id}",
"issued_by": "CN=localhost",
"subject": "CN=localhost",
"thumbprint": "2F6C0E796B8DAC4A1DDBF59F1714A19D9520B88A",
"valid_to": "2022-01-09T00:00:00Z"
},
"require_sni": "false"
},
{
"protocol": "http",
"binding_information": "*:80:",
"ip_address": "*",
"port": "80",
"hostname": ""
},
 {
"protocol": "net.tcp",
"binding_information": "808:*"
}
],
"application_pool": {
"name": "DefaultAppPool",
"id": "{application_pool_id}",
"status": "started"
},
"_links": {
"authentication": {
"href": "/api/webserver/authentication/{authentication_id}"
},
"authorization": {
"href": "/api/webserver/authorization/{authorization_id}"
},
"default_document": {
"href": "/api/webserver/default-documents/{default_document_id}"
},
"delegation": {
"href": "/api/webserver/feature-delegation?website.id={id}"
},
"directory_browsing": {
"href": "/api/webserver/directory-
browsing/{directory_browsing_id}"
},
"files": {
"href": "/api/webserver/files/{files_id}"
},
"handlers": {
"href": "/api/webserver/http-handlers/{handlers_id}"
},
"ip_restrictions": {
"href": "/api/webserver/ip-restrictions/{ip_restrictions_id}"
},
"logging": {
"href": "/api/webserver/logging/{logging_id}"
},
"modules": {
"href": "/api/webserver/http-modules/{modules_id}"
},
"request_filtering": {
"href": "/api/webserver/http-request-
filtering/{request_filtering_id}"
},
"request_monitor": {
"href": "/api/webserver/http-request-monitor/requests?
website.id={request_monitor_id}"
},
"request_tracing": {
"href": "/api/webserver/http-request-
tracing/{request_tracing_id}"
},
"response_compression": {
 "href": "/api/webserver/http-response-
compression/{response_compression_id}"
},
"response_headers": {
"href": "/api/webserver/http-response-
headers/{response_headers_id}"
},
"ssl": {
"href": "/api/webserver/ssl-settings/{ssl_id}"
},
"static_content": {
"href": "/api/webserver/static-content/{static_content_id}"
},
"vdirs": {
"href": "/api/webserver/virtual-directories?website.id={id}"
},
"webapps": {
"href": "/api/webserver/webapps?website.id={id}"
}
}
}

Web Site Bindings

The bindings of a web site determine what ports, protocols, and hostnames the site will
listen for. At the least, a binding must specify a protocol, ip adddress, and a port. The
binding_information property can be used to specify the ip address, port, and hostname.
The format of binding_information is '{ip_address}:{port}:{hostname}' for HTTP and
HTTPS protocols. A certificate is required for HTTPS bindings.

Creating a Web Site

Creating a web site requires a physical path to store the web site, the name of the web
site, and a set of bindings that the web site should listen on.

Creating an HTTP enabled web site

Creating a web site that listens on port 8081. POST /api/webserver/websites

{
"name": "Demonstration Site",
"physical_path": "C:\\inetpub\\wwwroot\\DemonstrationSite",
"bindings": [
{
 "protocol": "HTTP",
"port": "8081",
"ip_address": *
}
]
}

Creating an HTTPS enabled web site

To create a site with an HTTPS binding, a certificate must provided in the binding object.
Certificates are a resource available through the /api/certificates endpoint. To specify the
desired certificate in the binding, add the certificate resource and specify the certificate
id as shown below.

Creating a web site that listens for HTTPS requests on port 8082. POST
/api/webserver/websites

{
"name": "Demonstration Site",
"physical_path": "C:\\inetpub\\wwwroot\\DemonstrationSite",
"bindings": [
{
"protocol": "HTTPS",
"port": "8082",
"ip_address": *,
"certificate": {
"id": {certificate_id}
}
}
]
}

Creating in a specific application pool

To specify which application pool that a web site should be created for, add the
application_pool property to the body of the request. The application pool is identified
solely by its id property.

Creating a web site for a specific application pool. POST /api/webserver/websites

{
"name": "Demonstration Site",
"physical_path": "C:\\inetpub\\wwwroot\\DemonstrationSite",
 "bindings": [
{
"protocol": "HTTP",
"port": "8081",
"ip_address": *
}
],
"application_pool": {
"id": {application_pool_id}
}
}

Updating a Web Site

Updating web sites is done through patch requests. Sending a patch request with the
web site in the desired state will update the web site on the server to match.

Adding a binding
A common reason to update a web site is to add a binding. As an example, let us say
that there is a web site with a single binding on port 80, and we want to add a binding
that listens on port 8080. We should send a patch request that contains a bindings list
with both the bindings that we desire. Since the bindings property is a list, the bindings
that already exist on the web site should be sent as part of the request so that they are
not lost.

Adding a binding to a web site. PATCH /api/webserver/websites/{id}

{
"bindings": [
{
"protocol": "HTTP",
"port": "80",
"ip_address": *
},
{
"protocol": "HTTP",
"port": "8080",
"ip_address": *
}
]
}
Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Web Application Resource
Article • 07/25/2022

Applications provide a method to differentiate sections of a web site. An application

belongs to a single web site and will handle requests for the web site at the application
path. The application pool API allows consumers to create, read, delete, or update their
application pools.

GET /api/webserver/webapps/{id}

{
"location": "Default Web Site/demo-app",
"path": "/demo-app",
"id": "{id}",
"physical_path": "c:\\inetpub\\wwwroot\\demo-app",
"enabled_protocols": "http",
"website": {
"name": "Default Web Site",
"id": "{website_id}",
"status": "started"
},
"application_pool": {
"name": "DefaultAppPool",
"id": "{application_pool_id}",
"status": "started"
},
"_links": {
"authentication": {
"href": "/api/webserver/authentication/{authentication_id}"
},
"authorization": {
"href": "/api/webserver/authorization/{authorization_id}"
},
"default_document": {
"href": "/api/webserver/default-documents/{default_document_id}"
},
"directory_browsing": {
"href": "/api/webserver/directory-
browsing/{directory_browsing_id}"
},
"handlers": {
"href": "/api/webserver/http-handlers/{handlers_id}"
},
"ip_restrictions": {
"href": "/api/webserver/ip-restrictions/{ip_restrictions_id}"
},
"modules": {
"href": "/api/webserver/http-modules/{modules_id}"
 },
"request_filtering": {
"href": "/api/webserver/http-request-
filtering/{request_filtering_id}"
},
"request_tracing": {
"href": "/api/webserver/http-request-
tracing/{request_tracing_id}"
},
"response_compression": {
"href": "/api/webserver/http-response-
compression/{response_compression_id}"
},
"response_headers": {
"href": "/api/webserver/http-response-
headers/{response_headers_id}"
},
"ssl": {
"href": "/api/webserver/ssl-settings/{ssl_id}"
},
"static_content": {
"href": "/api/webserver/static-content/{static_content_id}"
},
"vdirs": {
"href": "/api/webserver/virtual-directories?webapp.id={id}"
}
}
}

Retrieving applications for a web site

The applications that belong to a web site can retrieved by providing the website id in
the GET request. Web site resources contain the link required to access their applications
in their HAL.

Listing the applications for a website. GET /api/webserver/webapps?website.id=

{website_id}

{
"webapps": [
{
"location": "Default Web Site/",
"path": "/",
"id": "{id}",
"_links": {
"self": {
"href": "/api/webserver/webapps/{id}"
}
}
 },
{
"location": "Default Web Site/demo-app",
"path": "/demo-app",
"id": "{id_1}",
"_links": {
"self": {
"href": "/api/webserver/webapps/{id_1}"
}
}
}
]
}

Creating an Application
Creating an application requires:

website: The web site that the application should be created for.
path: The virtual path that the application should exist at relative to the root of the
web site.
physical_path: The directory that the application should exist in in the file system.
The directory must exist.

Creating an application. POST /api/webserver/webapps

{
"path": "demo-app",
"physical_path": "C:\\inetpub\\wwwroot\\demo-app",
"website": {
"id": "{website_id}"
}
}

Using a specific application pool

To create an application in a specific application pool, add the application_pool
property to the request body.

Creating an application for a specific application pool. POST /api/webserver/webapps

 {
"path": "demo-app",
"physical_path": "C:\\inetpub\\wwwroot\\demo-app",
"website": {
"id": "{website_id}"
},
"application_pool": {
"id": "{application_pool_id}"
}
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Virtual Directory Resource
Article • 07/25/2022

Virtual directories provide a way to create the virtual file hierarchy that a web site
requires. The virtual directory API allows consumers to create, read, delete, or update
their virtual directories.

GET /api/webserver/virtual-directories/{id}

{
"location": "Default Web Site/demo-vdir",
"path": "/demo-vdir",
"id": "{id}",
"physical_path": "c:\\inetpub\\wwwroot\\demo-vdir",
"identity": {
"username": "",
"logon_method": "network_cleartext"
},
"webapp": {
"location": "Default Web Site/",
"path": "/",
"id": "{webapp_id}"
},
"website": {
"name": "Default Web Site",
"id": "{website_id}",
"status": "started"
}
}

Retrieving virtual directories for a Web Site

The virtual directories that belong to a web site can retrieved by providing the website
id in the GET request. Web site resources contain the link required to access their virtual
directories in their HAL.

Listing the virtual directories of a website. GET /api/webserver/virtual-directories?

website.id={website_id}

{
"virtual_directories": [
{
"location": "Default Web Site/",
 "path": "/",
"id": "{id}",
"_links": {
"self": {
"href": "/api/webserver/virtual-directories/{id}"
}
}
},
{
"location": "Default Web Site/demo-vdir",
"path": "/demo-vdir",
"id": "{id_1}",
"_links": {
"self": {
"href": "/api/webserver/virtual-directories/{id_1}"
}
}
}
]
}

Retrieving virtual directories for an application

The virtual directories that belong to an application can retrieved by providing the
application id in the GET request. Web application resources contain the link required to
access their virtual directories in their HAL.

Listing the virtual directories of an application. GET /api/webserver/virtual-directories?

webapp.id={webapp_id}

{
"virtual_directories": [
{
"location": "Default Web Site/demo-app/",
"path": "/",
"id": "{id}",
"_links": {
"self": {
"href": "/api/webserver/virtual-directories/{id}"
}
}
},
{
"location": "Default Web Site/demo-app/app-level-vdir",
"path": "/app-level-vdir",
"id": "{id_1}",
"_links": {
"self": {
"href": "/api/webserver/virtual-directories/{id_1}"
 }
}
}
]
}

Creating a Virtual Directory

Creating a virtual directory requires

A web site or web application for the virtual directory to belong to

A virtual path that is relative to the root of the web site or web app
A physical path that specifies the directory on the file system which the virtual
directory will reside in

Creating a virtual directory POST /api/webserver/virtual-directories

{
"path": "demo-vdir",
"physical_path": "C:\\inetpub\\wwwroot\\demo-vdir",
"website": {
"id": {website_id}
}
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Worker Process Resource
Article • 01/24/2019

Worker processes provide the execution environment for all web sites and applications
configured in IIS. Valuable information such as CPU utilization and memory footprint can
be obtained from the API to help monitor the health of worker processes and the web
server. The /api/webserver/worker-processes endpoint lists all the worker processes that
are currently running.

GET /api/webserver/worker-processes/{worker-process-id}

{
"name": "w3wp",
"id": "{worker-process-id}",
"status": "running",
"process_id": "45076",
"process_guid": "63e9cb86-592d-4080-9132-5a9bec85d7c3",
"start_time": "2017-03-08T09:42:34.9696447-08:00",
"working_set": "43098112",
"peak_working_set": "43098112",
"private_memory_size": "118493184",
"virtual_memory_size": "2215549431808",
"peak_virtual_memory_size": "2215550480384",
"total_processor_time": "00:00:00.2812500",
"application_pool": {
"name": "DefaultAppPool",
"id": "{app-pool-id}",
"status": "started"
},
"_links": {
"request_monitor": {
"href": "/api/webserver/http-request-monitor/requests?wp.id=
{worker-process-id}"
}
}
}

Filtering by Application Pool

The worker processes that are running for a given application pool can be obtained by
specifying the application pool's id at the worker processes endpoint.

GET /api/webserver/worker-processes?application_pool.id={application-pool-id}
 {
"worker_processes": [
{
"name": "w3wp",
"id": "{worker-process-id}",
"process_id": "45076"
}
]
}

Terminating A Worker Process

The API supports the ability to terminate a worker process by sending a DELETE request
to the worker processes endpoint at /api/webserver/worker-processes/{worker-process-id}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Certificate Resource
Article • 02/23/2019

Certificates provide the mechanism for web servers to prove their identity as well as
secure communication channels. The certificates API is essential to creating web sites
that serve content over HTTPS.

GET /api/certificates/{id}

{
"alias": "My Self Signed Certificate",
"id": "{id}",
"issued_by": "CN=localhost",
"subject": "CN=localhost",
"thumbprint": "1E927A29E966FA11A7C469BC565A9E00B11F5F95",
"signature_algorithm": "sha256RSA",
"valid_from": "2017-04-12T11:26:26Z",
"valid_to": "2019-04-12T11:26:26Z",
"version": "3",
"intended_purposes": [
"Client Authentication",
"Server Authentication"
],
"private_key": {
"exportable": "false"
},
"subject_alternative_names": [
"DNS Name=localhost",
"DNS Name=my-work-pc"
],
"store": {
"name": "My",
"id": "{store-id}",
"_links": {
"self": {
"href": "/api/certificates/stores/{store-id}"
}
}
}
}

Range Requests
It is not uncommon for a web server to have a very large amount of certificates. To
improve usability of the certificates API for these servers, the endpoint supports range
requests. Sending a HEAD request to the certificates endpoint will prompt the server to
respond with the total number of certificates that are available in the X-Total-Count
HTTP header. The certificates can then be requested in chunks by setting the Range
header in subsequent requests.

HEAD /api/certificates

200 OK
x-total-count: 100

Retreiving the second and third certificates out of 100

GET /api/certificates
Access-Token: Bearer {Access-Token}
Range: certificates=1-2

Certificate stores
All certificates belong to a certificate store. A list of the available certificate stores can be
retreived from the certificate stores endpoint /api/certificates/stores. These certificate
stores have a claims property which specify what operations are allowed on the
certificates inside the store. This access is configurable via the certificates section of the
application settings file. Currently certificate stores only support read operations. In the
future the API may support importing, exporting, deleting, and creating certificates.

GET /api/certificates/stores

{
"stores": [
{
"name": "My",
"id": "{store-id}",
"_links": {
"self": {
"href": "/api/certificates/stores/{store-id}"
}
}
},
{
"name": "WebHosting",
 "id": "{store-id}"
// _links omitted
},
{
"name": "IIS Central Certificate Store",
"id": "{store-id}"
// _links omitted
}
]
}

Listing Certificates for a Specific Store

The certificates API supports filtering certificates by store. To do this, the id property of
the target certificate store should be retreived. This can be done through the certificate
stores endpoint. Then a request should be made to the certificates endpoint that
specifies the store.id field in the query string. The following request will retreive all
certificates for the built in Web Hosting certificate store.

GET /api/certificates?store.id={store-id}

{
"certificates": [
{
"alias": "WebHostCert",
"id": "{cert-id}",
"issued_by": "CN=localhost",
"subject": "CN=localhost",
"thumbprint": "8E7933F41998C507B30F0E0AC8B548A903FE7843",
"valid_to": "2019-02-28T14:32:33Z",
"_links": {
"self": {
"href": "/api/certificates/{cert-id}"
}
}
}
]
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No
Get help at Microsoft Q&A
Files
Article • 07/26/2019

The IIS Administration API provides a set of file APIs to interact directly with the file
system. This means the API can be used locally or remotely to deploy content, make
edits or check if files are up to date.

General Files (/api/files)

The /api/files endpoint exposes the metadata and content of files and directories on the
machine. The files available through this api are limited to those specified in the files
configuration section of the appsettings.json file. Querying the /api/files endpoint
without specifying a directory will list the locations present in the configuration. These
locations represent the root of all file system paths available through the API. Files can
be created, deleted and manipulated with the standard HTTP post, delete, and patch
verbs as long as the file path has the claims necessary to perform the operation.

Examples
File

{
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png",
"exists": "true",
"size": "98757",
"created": "2017-01-09T18:08:33.5130112Z",
"last_modified": "2017-01-09T17:48:13.6180477Z",
"last_access": "2017-01-09T17:48:13.6180477Z",
"e_tag": "1d26aa08c67ed45",
"parent": {
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot"
},
"claims": [
"read",
"write"
]
}
Directory

{
"name": "wwwroot",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot",
"exists": "true",
"created": "2017-01-09T18:08:33.1380257Z",
"last_modified": "2017-01-30T17:01:15.2619212Z",
"last_access": "2017-01-30T17:01:15.2619212Z",
"total_files": "7",
"parent": {
"name": "inetpub",
"id": "a-nA1LZCBZ9jIqxr6e2uWg",
"type": "directory",
"physical_path": "C:\\inetpub"
},
"claims": [
"read",
"write"
]
}

Web Server Files (/api/webserver/files)

The /api/webserver/files endpoint exposes the virtual file structure created by IIS. All file
resources under this endpoint belong to some web site and the path of that file is
relative to the website that it belongs to. This allows web sites to be treated as file
system root, which is desirable in web server scenarios. Virtual directories are included
among the normal directories for a complete view of the virtual file hierarchy of a
website.

All web server files have a reference to a file_info which is the file metadata that can be
obtained from the /api/files endpoint.

Examples
Web File

{
"name": "iisstart.png",
"id": "{id}",
 "type": "file",
"path": "/iisstart.png",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "iisstart.png",
"id": "{id}",
"type": "file",
"physical_path": "C:\\inetpub\\wwwroot\\iisstart.png"
}
}

Web Directory

{
"name": "imgs",
"id": "{id}",
"type": "directory",
"path": "/imgs",
"parent": {
"name": "",
"id": "{id}",
"type": "application",
"path": "/"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
"status": "started"
},
"file_info": {
"name": "imgs",
"id": "{id}",
"type": "directory",
"physical_path": "C:\\inetpub\\wwwroot\\imgs"
}
}
Copying/Moving Files (/api/files/copy |
/api/files/move)
The API supports copying and moving files via the /api/files/copy and /api/files/move
endpoints. The process of copying a file is performed by executing a POST request to
the API that describes the desired copy operation.

POST

{
"name":"{optional name of the destination file}",
"file": {
"id": "{id property of the file to copy}"
},
"parent": {
"id": "{id property of the directory to copy to}"
}
}

Manipulating File Content (/api/files/content)

The resources under the /api/files route contain only metadata for files. To manipulate
the content of a file one must use the /api/files/content/{id} route. This route uses the
application/octet-stream content type for transmitting data. Performing a GET request to
the content URL of a file will retreive the raw bytes of the file. This operation supports
HTTP range requests so the file can be downloaded in chunks. Performing a PUT request
to the content URL of the file will replace the content of the file with the request body.
This operation supports HTTP content-range requests to enable random access
manipulation of files.

Download 2nd 500 bytes of a file

GET /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Range: bytes=500-999

Edit 2nd 500 bytes of a 1000 byte file

 PUT /api/files/content/{id}
Access-Token: Bearer {Access-Token}
Content-Range: bytes 500-999/1000
Content-Length: 500

Downloading Files (/api/files/download)

Files can be downloaded through the /api/files/content endpoint of the API. The
drawback of this endpoint is that since it is under the api route, it requires an access
token. This means that the file cannot be downloaded via a browser. The
/api/files/download endpoint enables the creation of temporary download links. These
download links are unique, randomly generated, and do not require an access token.
Generated download links take the form of /downloads/{random_sequence}. An optional
time-to-live (ttl) parameter is available when generating a download link to specify how
long the download link should be available. The default is five seconds.

When a download is generated, the link for the download is returned in the Location
header of the HTTP response.

POST

{
"file": {
"id": "{id of the file to download}"
},
"ttl": "10000"
}

Using File Shares

The files API can be used to manage files located on file shares. To enable this
functionality, the file share must allow the necessary file system permissions to the
principal representing the machine that the API is running on. As an example, suppose
there is shared content located at \\share\images and we want to allow an API running
on a web server named web-prod-1 to enumerate these files. To allow this, an
administrator must modify the ACL of the \\share\images directory to allow READ access
to the web-prod-1 Active Directory object. Once this is done the service on the web-
prod-1 machine will be able to access this directory, read the files, and then expose
them through the API.
Locations - File API Roots (/api/files/locations)
The API's file system access is limited to a set of root folders, called locations, that are
specified in the appsettings file. These locations appear as roots from the perspective of
the file API but on the physical drive they may be nested folders, the root of a drive, or
even a network share. For each location, read and write access is controlled
independently. Any paths on the file system that do not fall within a location will not be
seen by the file system API.

Starting with version 2.2.0, location settings are accessible through the
/api/files/locations endpoint. This endpoint is locked down to users in the owners user
group of the API. This means Windows Authentication is required to access the locations
endpoint. Adding or removing locations will add or remove file system access from the
API. This endpoint supports GET, PATCH, POST, and DELETE for creating, editing, and
deleting existing locations. Editing locations has no effect on the physical files, it only
manipulates the API's view of the file system.

The Default Locations Configuration

{
"locations": [
{
"alias": "inetpub",
"id": "{id}",
"path": "C:\\inetpub",
"claims": [
"read"
]
}
]
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Monitoring
Article • 01/24/2019

The monitoring API provides performance and health data for the web server, web sites,
and application pools. This data can be used to measure how effectively resources are
being used.

Web Server Monitoring

(/api/webserver/monitoring)
The /api/webserver/monitoring endpoint exposes aggregrated performance data for the
web server. These data points include networking, CPU, memory, HTTP requests, and
caching. With the exception of some properties such as system_in_use, all data is scoped
down to the web server. For instance, private_working_set only includes memory used by
webserver worker processes.

Example
Web Server Monitoring Resource

{
"id": "{id}",
"network": {
"bytes_sent_sec": "59486",
"bytes_recv_sec": "8313",
"connection_attempts_sec": "0",
"total_bytes_sent": "4797480792",
"total_bytes_recv": "670503816",
"total_connection_attempts": "1",
"current_connections": "1"
},
"requests": {
"active": "0",
"per_sec": "64",
"total": "5197703"
},
"memory": {
"handles": "358",
"private_bytes": "9097216",
"private_working_set": "8032256",
"system_in_use": "6734737408",
"installed": "15403110400"
},
 "cpu": {
"threads": "24",
"processes": "1",
"percent_usage": "0",
"system_percent_usage": "14"
},
"disk": {
"io_write_operations_sec": "1",
"io_read_operations_sec": "1",
"page_faults_sec": "0"
},
"cache": {
"file_cache_count": "2",
"file_cache_memory_usage": "699",
"file_cache_hits": "18506471",
"file_cache_misses": "46266060",
"total_files_cached": "10",
"output_cache_count": "0",
"output_cache_memory_usage": "0",
"output_cache_hits": "0",
"output_cache_misses": "18506478",
"uri_cache_count": "2",
"uri_cache_hits": "18506452",
"uri_cache_misses": "26",
"total_uris_cached": "13"
}
}

Field Explanations
Network

bytes_sent_sec: The number of bytes that the web server sent in the last second.

bytes_recv_sec: The number of bytes that the web server received in the last second.

connection_attempts_sec: The number of client connections that have been attempted

in the last second.

total_bytes_sent: The number of bytes sent since the web server started.

total_bytes_recv: The number of bytes received since the web server started.

total_connection_attempts: The number of client connections that have been attempted

since the web server started.

current_connections: The number of active connections that are open on the web server.

Requests
active: The number of requests that are currently being processed by the web server.

per_sec: The number of requests that have been served in the past second.

total: The number of requests that have been served since the web server started.

Memory

handles: The number of handles that are currently open in web server processes.

private_bytes: The total private bytes being used by all web server processes.

private_working_set: The total private working set being used by all web server
processes.

system_in_use: The total memory in use by the entire system.

installed: The total installed memory.

CPU

threads: The number of threads currently active in web server processes.

processes: The number of processes being used by the web server to process requests.

percent_usage: The percentage of CPU being used by web server processes.

system_percent_usage: The percentage of CPU being used by the entire system.

Disk

io_write_operations_sec: The number of write operations performed by all webserver

processes in the last second.

io_read_operations_sec: The number of read operations performed by all webserver

processes in the last second.

page_faults_sec: The number of page faults experienced by all webserver processes in

the last second.

Cache

file_cache_count: Current number of files whose content is in the user-mode cache.

file_cache_memory_usage: Current number of bytes used for the user-mode file cache.

file_cache_hits: Number of successful lookups in the user-mode file cache since the web
server started.
file_cache_misses: Number of unsuccessful look ups in the user-mode file cache since
the web server started.

total_files_cached: Number of files whose content was ever added to the user-mode
cache since the web server started.

output_cache_count: Current number of items is in the output cache.

output_cache_memory_usage: Current number of bytes used for the output cache.

output_cache_hits: Number of successful lookups in the output cache since the web
server started.

output_cache_misses: Number of unsuccessful lookups in the output cache since the

web server started.

uri_cache_count: Number of URI information blocks that are currently in the user-mode
cache.

uri_cache_hits: Number of successful look ups in the user-mode URI cache since the web
server started.

uri_cache_misses: Number of unsuccessful look ups in the user-mode URI cache since
the web server started.

total_uris_cached: Number of URI information blocks that have been added to the user-
mode cache since the web server started.

Web Site Monitoring

(/api/webserver/websites/monitoring/{id})
The /api/webserver/websites/monitoring endpoint exposes performance data for an
individual web site. The data is similar to what is available from the web server
monitoring resource.

Note: This data includes information from the application pool that the web site runs in.
If multiple web sites are running in the same application pool, the web site data taken
from the application pool may be invalid. Assign one site per application pool for
accurate performance measurement at the web site level.

Example
Web Site Monitoring Resource
{
"id": "{id}",
"uptime": "88170",
"network": {
"bytes_sent_sec": "31280",
"bytes_recv_sec": "4371",
"connection_attempts_sec": "0",
"total_bytes_sent": "4939609870",
"total_bytes_recv": "690368010",
"total_connection_attempts": "1",
"current_connections": "1"
},
"requests": {
"active": "0",
"per_sec": "33",
"total": "5351689"
},
"memory": {
"handles": "358",
"private_bytes": "9097216",
"private_working_set": "8032256",
"system_in_use": "6704680960",
"installed": "15403110400"
},
"cpu": {
"percent_usage": "0",
"threads": "24",
"processes": "1"
},
"disk": {
"io_write_operations_sec": "1",
"io_read_operations_sec": "1",
"page_faults_sec": "0"
},
"cache": {
"file_cache_count": "2",
"file_cache_memory_usage": "699",
"file_cache_hits": "10703511",
"file_cache_misses": "26758783",
"total_files_cached": "2",
"output_cache_count": "0",
"output_cache_memory_usage": "0",
"output_cache_hits": "0",
"output_cache_misses": "10703512",
"uri_cache_count": "2",
"uri_cache_hits": "10703508",
"uri_cache_misses": "4",
"total_uris_cached": "2"
},
"website": {
"name": "Default Web Site",
"id": "{id}",
 "status": "started"
}
}

Field Explanations
Most of the fields are the same as the web server resource. A few additional fields are
present as indicated below.

uptime: The number of seconds that have elapsed since the web site started.

website: The web site resource that the data belongs to.

Application Pool Monitoring

(/api/webserver/application-
pools/monitoring/{id})
The /api/webserver/application-pools/monitoring endpoint exposes performance data
for an individual application pool. The data is similar to what is available from the web
server monitoring resource. Some properties present in the web server are not available
in the context of an application pool.

Example
Application Pool Monitoring Resource

{
"id": "{id}",
"requests": {
"active": "0",
"per_sec": "76",
"total": "5371766"
},
"memory": {
"handles": "358",
"private_bytes": "9097216",
"private_working_set": "8032256",
"system_in_use": "6742872064",
"installed": "15403110400"
},
"cpu": {
"percent_usage": "0",
"threads": "24",
 "processes": "1"
},
"disk": {
"io_write_operations_sec": "0",
"io_read_operations_sec": "0",
"page_faults_sec": "0"
},
"cache": {
"file_cache_count": "2",
"file_cache_memory_usage": "699",
"file_cache_hits": "10743531",
"file_cache_misses": "26858833",
"total_files_cached": "2",
"output_cache_count": "0",
"output_cache_memory_usage": "0",
"output_cache_hits": "0",
"output_cache_misses": "10743532",
"uri_cache_count": "2",
"uri_cache_hits": "10743528",
"uri_cache_misses": "4",
"total_uris_cached": "2"
},
"application_pool": {
"name": "DefaultAppPool",
"id": "{id}",
"status": "started"
}
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

The Central Certificate Store
Article • 01/24/2019

The Central Certificate Store (CCS) feature of IIS provided a mechanism to place
certificates in a file share for use by multiple web servers. This feature can be enabled,
disabled, and configured through the CCS API /api/webserver/centralized-
certificates/{id}.

Requirements
To enable the Central Certificate Store, the API must have read access to the physical
path that the store will be configured to use. This access is granted in the files section of
the application settings. Attempting to set the path of the CCS to a physical path that is
not allowed will result in a 403 Forbidden error.

Checking if CCS is enabled

If the central certificate store feature is disabled, the ccs endpoint will return a 404
Feature Not Installed response.

GET /api/webserver/centralized-certificates/{id}, when CCS is not enabled

{
"title": "Not found",
"detail": "IIS feature not installed",
"name": "IIS Central Certificate Store",
"status": "404"
}

Enabling CCS
To enable the Central Certificate Store, a POST request should be sent to the CCS API
endpoint along with all the necessary data to enable the feature.

POST /api/webserver/centralized-certificates/{id}

{
"path": "\\\\FileShare\\certs",
 "identity": {
"username": "{Username of windows identity used to access file
share}"
"password": "{Password of windows identity used to access file
share}"
},
"private_key_password": "{Password used to encrypt private keys}"
}

Updating CCS
The Central Certificate Store settings can be modified using a PATCH request with the
updated settings.

Disabling CCS
To disable the Central Certificate Store, a DELETE request should be sent to the CCS
endpoint.

DELETE /api/webserver/centralized-certificates/{id}

204 No Content

Reading CCS Certificates

When the central certificate store is enabled its certificates can be viewed through the
certificates API. In order to populate the CCS certificates, the file share that the CCS is
configured to use must allow READ access to the computer that the API is running on.
This behavior is the same as using a file share with the files API.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

HTTP Request Tracing
Article • 07/26/2019

HTTP request tracing is a feature of IIS that provides a way to determine what exactly is
happening with a request. This includes any form of authentication, which handler was
used, and how long each step took in the pipeline. Enabling request tracing is a useful
way to diagnose unexpected or undesirable behavior.

Feature Settings (/api/webserver/http-request-

tracing)
The HTTP request tracing feature creates trace files based on a configured set of rules.
The information in the trace files is determined by what providers are avaialable for that
rule. The feature settings for request tracing deal with the generation of the trace files.

GET /api/webserver/http-request-tracing/{request-tracing-id}

{
"id": "{request-tracing-id}",
"scope": "",
"metadata": {
"is_local": "true",
"is_locked": "false",
"override_mode": "inherit",
"override_mode_effective": "allow"
},
"enabled": "true",
"directory": "%SystemDrive%\\inetpub\\logs\\FailedReqLogFiles",
"maximum_number_trace_files": "50",
"website": null,
"_links": {
"providers": {
"href": "/api/webserver/http-request-tracing/providers?
http_request_tracing.id={request-tracing-id}"
},
"rules": {
"href": "/api/webserver/http-request-tracing/rules?
http_request_tracing.id={request-tracing-id}"
}
}
}
Trace Providers (/api/webserver/http-request-
tracing/providers)
The providers for HTTP request tracing determine what information will be provided
whenever a trace rule is triggered. IIS comes with a set of default providers that provide
most of the information a consumer will want.

GET /api/webserver/http-request-tracing/providers/{provider-id}

{
"name": "ASPNET",
"id": "{provider-id}",
"guid": "{aff081fe-0247-4275-9c4e-021f3dc1da35}",
"areas": [
"Infrastructure",
"Module",
"Page",
"AppServices"
],
"request_tracing": {
"id": "{request-tracing-id}",
"scope": "",
"_links": {
"self": {
"href": "/api/webserver/http-request-tracing/{request-
tracing-id}"
}
}
}
}

Trace Rules (/api/webserver/http-request-

tracing/rules)
Trace rules generate request tracing logs whenever a request is executed that meets the
conditions specified in the trace rule. Trace rules can trigger based on status code,
execution time, and path.

GET /api/webserver/http-request-tracing/rules/{rule-id}

{
"path": "*",
 "id": "{rule-id}",
"status_codes": [
"101-999"
],
"min_request_execution_time": "2147483647",
"event_severity": "ignore",
"custom_action": {
"executable": "",
"params": "",
"trigger_limit": "1"
},
"traces": [
{
"allowed_areas": {
"Authentication": "true",
"Security": "true",
"Filter": "true",
"StaticFile": "true",
"CGI": "true",
"Compression": "true",
"Cache": "true",
"RequestNotifications": "true",
"Module": "true",
"FastCGI": "true",
"WebSocket": "true"
},
"provider": {
"name": "WWW Server",
"id": "{provider-id}",
"_links": {
"self": {
"href": "/api/webserver/http-request-
tracing/providers/{provider-id}"
}
}
},
"verbosity": "warning"
}
],
"request_tracing": {
"id": "{request-tracing-id}",
"scope": "",
"_links": {
"self": {
"href": "/api/webserver/http-request-tracing/{request-
tracing-id}"
}
}
}
}

Creating a Request Tracing Rule

A request tracing rule must specify which request tracing section it belongs to when it is
being created, and also should specify any providers that should log information for the
generated log file. In this example a rule is created that only generates trace logs for
requests to index.html. The logs will include information from the WWW Server trace
provider.

POST /api/webserver/http-request-tracing/rules

{
"path": "index.html",
"status_codes": [
"100-999"
],
"traces": [
{
"allowed_areas": {
"Authentication": "true",
"Security": "true",
"Filter": "true",
"StaticFile": "true",
"CGI": "true",
"Compression": "true",
"Cache": "true",
"RequestNotifications": "true",
"Module": "true",
"FastCGI": "true",
"WebSocket": "true"
},
"provider": {
"id": "{www-server-provider-id}"
},
"verbosity": "warning"
}
],
"request_tracing": {
"id": "{request-tracing-id}"
}
}

Trace Logs (/api/webserver/http-request-

tracing/traces)
The Microsoft IIS Administration API provides an endpoint to view data for the trace
logs that have been generated. This information helps quickly determine which trace file
is of interest instead of having to open each file individually.
GET /api/webserver/http-request-tracing/traces/{trace-id}

{
"id": "{trace-id}",
"url": "http://localhost:80/favicon.ico",
"method": "GET",
"status_code": "404",
"date": "2017-03-02T15:34:17.0627155-08:00",
"time_taken": "0",
"process_id": "8172",
"activity_id": "{8000009D-0001-F700-B63F-84710C7967BB}",
"file_info": {
"name": "fr000001.xml",
"id": "{file-id}",
"type": "file",
"physical_path":
"c:\\inetpub\\logs\\FailedReqLogFiles\\W3SVC1\\fr000001.xml",
"_links": {
"self": {
"href": "/api/files/{file-id}"
}
}
},
"request_tracing": {
"id": "{request-tracing-id}",
"scope": "Default Web Site/",
"_links": {
"self": {
"href": "/api/webserver/http-request-tracing/{request-
tracing-id}"
}
}
}
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Api Keys
Article • 02/23/2019

The Microsoft IIS Administration API allows generation and viewing of API key
information through secured endpoints.

Access Token Info (/api/access-token)

This endpoint provides non-sensitive information about the access token being used for
the request.

GET /api/access-token

{
"id": "{access-token-id}",
"expires_on": "2018-02-02T16:25:31.4003337Z",
"type": "SWT",
"api_key": {
"purpose": "Admin",
"id": "{api-key-id}",
"_links": {
"self": {
"href": "/security/api-keys/{api-key-id}"
}
}
}
}

API Keys (/security/api-keys)

This endpoint allows for programmatic creation and deletion of API keys. This is useful
for generating API keys that will only exist for the scope of a scripting session or for
managing API keys with a central application. The API keys endpoint is under the
/security location, which means by default only Administrators and IIS Administrators
have access to it.

GET /security/api-keys/{api-key-id}

{
"purpose": "Admin",
 "id": "{api-key-id}",
"created_on": "2017-02-02T16:25:31.4003337Z",
"last_modified": "2017-02-02T16:25:31.4003337Z",
"expires_on": "2018-02-02T16:25:31.4003337Z",
"_links": {
"access_token": {
"href": "/security/access-tokens/{access-token-id}"
}
}
}

Creating an API Key

Creating an API key is a special task that requires two requests. The extra request is used
to prevent CSRF . First the user must query the API keys endpoint and receive a special
token from the XSRF-TOKEN header. Then the user can create the API key by specifying
the XSRF-TOKEN header in the creation request.

Note: XSRF-TOKEN is sent as an HTTP header.

Client
Server
|
|
| GET /security/api-keys
|
| ---------------------------------------------->
|
|
|
|
|
| XSRF-TOKEN:
{value} |
| <--------------------------
-------------------- |
|
|
|
|
| POST /security/api-keys
|
| XSRF-TOKEN: {value}
|
|
|
| {
|
 | "purpose": "Admin"
|
| }
|
| ---------------------------------------------->
|
|
|
|
|
| {
|
| "access_token" : "
{access-token-value}" |
| }
|
| <--------------------------
-------------------- |

POST Request for API Key Creation

The POST request section of API key generation is where parameters for the API key can
be specified. This is an example of a POST body that creates an API key with a specific
purpose and expiration date.

{
"purpose": "Admin",
"expires_on": "2018-02-02T16:25:31.4003337Z",
}

Deleting an API Key

API Keys can be deleted by performing a DELETE request at the api-key's endpoint
/security/api-keys/{api-key-id}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Installing IIS Components
Article • 07/26/2019

IIS and its components are exposed by Windows as optional features. This provides a
way for users to enable only the features of IIS that they need for their sites to operate.
As a side effect, when configuring IIS through the API it is possible that a feature, for
example Windows Authentication, may not yet be installed on the machine. Historically,
enabling IIS features was done through DISM.exe, PowerShell commands, or the
Windows Optional Feature UI. The IIS Administration API exposes a simple method to
install/uninstall these features so that consumers do not have to change environments
in order to enable the features that they depend on.

Checking If a Feature Is Installed

The first step of managing a feature is to check if it is installed. For any IIS feature we
can determine this by sending a request to its API endpoint. If the endpoint returns a
200 OK response, the feature is installed. If the feature is not installed, the API will return
a 404 Not Found response with a Feature Not Installed JSON error object in the body.
This example will use the default document feature of IIS. We check to see if the default
document is enabled by sending a GET request to the default document endpoint. We
use scope in the query string with an empty value to specify that we are targetting the
web server scope.

GET /api/webserver/default-documents?scope=

Feature Is Not Installed

404 Not Found

{
"title": "Not found",
"detail": "IIS feature not installed",
"name": "Default Document",
"status": "404"
}

Feature Is Installed
 200 OK

{
"id": "{id}",
"enabled": "true",
"scope": "",
"metadata": {
"is_local": "true",
"is_locked": "false",
"override_mode": "allow",
"override_mode_effective": "allow"
},
"website": null
}

Installing a Feature
Feature installation is performed by issuing a POST request to the feature's endpoint.
Some IIS features such as the Central Certificate Store require initial settings to be
provided when installing. As an example, suppose the default document feature was
returning the 404 Feature Not Installed response. Sending a POST request to to the
default documents endpoint installs the feature and then returns the features settings.

POST /api/webserver/default-documents

HTTP Response

201 CREATED
Location: /api/webserver/default-documents/{id}

{
"id": "{id}",
"enabled": "true",
"scope": "",
"metadata": {
"is_local": "true",
"is_locked": "false",
"override_mode": "allow",
"override_mode_effective": "allow"
},
"website": null
}
Uninstalling a Feature
IIS features can be uninstalled by issuing a DELETE request to the feature at the web
server level. For IIS features that support configuration at web site and application levels,
one can verify that the object represents the web server scope by ensuring the scope
field is empty.

First get the URI of the feature to uninstall.

GET /api/webserver

{
"id": "{id}",
"_links": {
... // Other features omitted
"default_document": {
"href": "/api/webserver/default-documents/{def-doc-id}"
}
}
}

Then, issue the DELETE request to the features endpoint

DELETE /api/webserver/default-documents/{def-doc-id}

204 NO CONTENT

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

CRUD (Create, Read, Update, Delete)
Article • 01/24/2019

The IIS Administration API provides direct access to resources on the system. Many of
these resources allow create, read, update and delete operations. The REST API maps
CRUD operations to HTTP methods. The following table specifies which HTTP method
maps to which operation.

CRUD Operation HTTP Method

Create POST

Read GET

Update PATCH / PUT

Delete DELETE

Create (POST)
Resources are created by sending HTTP POST requests to the API. The type of resource
is determined by the URL of the request. The body of the request should contain a JSON
object describing the resource to create. The object in the request body determines the
initial state of the resource will be when it is created. Some resources require certain
properties be provided when they are created, others can be created with an empty
JSON object.

Creating a resource while setting the name property. POST

{
"name": "Example Resource Name"
}

Creating a resource that belongs to another

Sometimes resources are created that are meant to belong to another resource. For
example, if applications must belong to a web site and someone wanted to create a new
application then they would specify that relationship during the creation of the
application as shown below.
Creating an application for a web site. POST

{
"path": "/MyApp",
"physical_path": "c:/sites/mysite/myapp",
"website": {
"id": {website_id}
}
}

Read (GET)
Resources are retrieved by performing HTTP GET requests. There are two main methods
to retrieve resources. The first method involves requesting a list of resources, the second
method is when a single resource is requested. Requests to a single resource are marked
by the presence of the resource id in the URL of the request. Sometimes, singular
resources can also be specified through query string paremeters in the URL. This
behavior depends on the individual API endpoint.

Retrieving multiple resources

Reading lists of resources is done by requesting a resource endpoint without specifying
an individual resources id. Sometimes resources require query string parameters or else
they cannot produce valid lists. For example IIS applications live at the
/api/webserver/webapps endpoint, but requesting that endpoint alone would produce
no information. This is because a web site must be specified to tell the API which
applications should be shown. So consumers would request /api/webserver/webapps?
website.id={website_id} to see a list of applications.

Retrieving a list of resources. GET /api/websites

{
"websites": [
{
"name": "Default Web Site",
"id": "{id}",
"status": "started",
"_links": {
"self": {
"href": "/api/webserver/websites/{id}"
}
 }
},
{
"name": "My Site",
"id": "{id_1}",
"status": "started",
"_links": {
"self": {
"href": "/api/webserver/websites/{id_1}"
}
}
}
{
"name": "docs",
"id": "{id_2}",
"status": "started",
"_links": {
"self": {
"href": "/api/webserver/websites/{id_2}"
}
}
}
]
}

Retrieving individual resources

Resources are retrieved on an individual basis by providing the id of the resource in the
URL of the resource endpoint. Some API endpoints also allow specifying individual
resources by providing uniquely identifying query string parameters. For example, a file
can be retrieved by providing the id of the file in the URL or by providing the
physical_path of the file.

The file resource allows multiple methods to retrieve individual files:

/api/files/{id}
/api/files?physical_path={physical path of the file}

The files endpoint provides this behavior because only one file can exist for any given
physical path, so it is a uniquely identifying query string parameter.

Update (PATCH / PUT)

Updates are performed by issuing HTTP PATCH requests to the URL that the resource is
located at. When a PATCH request is performed, the properties of the request body are
read, and if the resource has a property with the same name the property of the
resource will be set to the new value.
Example resource before PATCH

{
"name": "My Site",
"id": "12345",
"physical_path": "c:\\sites\\mysite"
"_links": {
"self": {
"href": "/api/webserver/websites/{12345}"
}
}
}

Performing the PATCH request

Patch request to update the name of the resource. PATCH
/api/webserver/websites/12345

{
"name": "My Site 2"
}

Resource after PATCH

{
"name": "My Site 2",
"id": "12345",
"physical_path": "c:\\sites\\mysite"
"_links": {
"self": {
"href": "/api/webserver/websites/{12345}"
}
}
}

Delete (DELETE)
Resources are deleted by sending an HTTP DELETE request to the URL that the resource
is located at. This is the URL that contains the id of the resource.
Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Scoping Configuration Changes/Access
Article • 07/26/2019

The IIS configuration system is a hierarchy that extends from the root web server
configuration to as far down as individual folders with a web application. The root
configuration file is named applicationHost.config and it resides in the IIS installation
directory. The rest of a web application's configuration exists in web.config files within
the application's directories. One benefit of using web.config files is that application's
can introduce configuration at different paths without affecting the web server as a
whole. At the same time, it is possible to define configuration in the root
applicationHost.config that targets only a specific path inside a specific web application.
This means there are two different ways to think of configuration scoping.

1. Reading/modifying configuration for an arbitrary path of a web application.

2. Modifying configuration for a specific path, but placing the configuration in a
configuration file at a higher level in the configuration hierarchy.

Example: Modifying a setting for Default Web Site/MyApp/MyFolder and

placing it in the web.config file located in the root of Default Web Site

Targeting a Specific Path Within a Web

Application
Querying configuration at a certain path is done by using the scope query filter.

Example (query string is not URL encoded for readability):

GET https://localhost:55539/api/webserver/http-request-filtering?
scope=Default Web Site/MyApp/MyFolder

This request will tell the API to query the request filtering settings for the MyFolder
directory within the MyApp application of the Default Web Site. The request filtering
resource that is returned will have the id necessary to modify the settings at that level
within the configuration system.

Setting Configuration and Storing It At A

Higher Level
The most common use case of this capability is to set configuration settings that only
web server administrators have access to touch. This is usually done for things that
might affect the overall security of the Web Server. Usually these settings cannot be
defined in the web.config files for an application so a web adminsitrator can configure
the applications and tell the settings to reside in the applicationHost.config file. This is
implemented in the applicationHost.config file through the use of a <location> element
that points to the configuration path that the settings should affect.

To achieve this, use config_scope in the body of a PATCH request being used to modify
settings. The value of the config_scope property should be the web server path to the
configuration file that the settings should reside in. For example the empty path "" refers
to the root applicationHost.config file and the path "Default Web Site/MyApp" refers to
the web.config file in the MyApp application within the Default Web Site.

Example:

Assume that the goal is to enable directory browsing for the path Default Web
Site/MyApp/MyFolder, the id for this resource is WXYZ, and the settings should be stored
in the applicationHost.config file.

PATCH https://localhost:55539/api/webserver/directory-browsing/WXYZ

{
"enabled": "true",
"config_scope": ""
}

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A

Hypertext Application Language (HAL)
Article • 01/24/2019

The IIS Administration API includes special data in all of its resources called Hypertext
Application Language (HAL). HAL is a set of conventions that provide a standardized
way to link resources. HAL is only included in resources when the client includes
application/hal+json in the Accept header of their HTTP requests.

_links
The _links property is the most prevalent form of HAL used in the API. The _links object
contains members indicating how to retrieve related resources.

A resource including _links, some _links members have been excluded.

{
"name": "Default Web Site",
"id": "{id}",
"physical_path": "%SystemDrive%\\inetpub\\wwwroot"
.
.
.
"application_pool": {
"name": "DefaultAppPool",
"id": "{app_pool_id}",
"status": "started",
"_links": {
"self": {
"href": "/api/webserver/application-pools/{app_pool_id}"
}
}
},
"_links": {
"authentication": {
"href": "/api/webserver/authentication/{authentication_id}"
},
"self": {
"href": "/api/webserver/websites/{id}"
},
"webapps": {
"href": "/api/webserver/webapps?website.id={id}"
}
}
}
This example resource is a web site in IIS. The _links property tells the consumer how to
get to the authentication settings, how to view the web site's applications for the web
site, and also the URI of the resource.

Self
Every resource that includes _links has a self link. This link provides the URI that the
resource lives at. This URI is the same one that PATCH and DELETE requests should be
sent to when updating or deleting the resource.

Requesting HAL
HAL is an augmentation to the JSON data format. When a resource includes HAL it has a
content type of application/hal+json. In order to receive HAL from the API, clients must
specify application/hal+json in the Accept header of their HTTP requests.

Feedback
Was this page helpful? ﾂ Yes ﾄ No

Get help at Microsoft Q&A