Export (0) Print
Expand All
8 out of 11 rated this helpful - Rate this topic

Web Sites Management REST API Reference

Updated: January 15, 2014

This documentation describes how to perform common tasks in Windows Azure Web Sites by using the Windows Azure Web Sites management REST API.

noteNote
To retrieve (HTTP GET) an existing subscription by using the REST API, see Get Subscription.

  • A valid Windows Azure account and an active Windows Azure subscription are required. This documentation assumes that you already have an active subscription and associated subscription ID.

  • A management certificate for your Windows Azure subscription. A management certificate is required to authenticate client access to resources in your subscription. You must use an X-509 v3 certificate that contains a public key and has a .cer file name extension. For information on how to create a management certificate, see Create a Management Certificate for Windows Azure. The management certificate must reside in the default Personal certificate store on your local computer and must also be uploaded to your Windows Azure account. To upload a management certificate to Windows Azure, in the main Management Portal, choose the Settings page from the pane on the left. Under Management Certificates, at the bottom of the page, choose Upload to upload the .cert file to your account.

    noteNote
    You can upload more than one management certificate to your Windows Azure subscription. Each management certificate is associated with your subscription, and is independent of any cloud service or deployment.To simplify management, it's a good idea to limit the number of management certificates and reuse existing ones.

The Windows Azure Web Sites management API provides a RESTful set of web services that interact with Windows Azure Web Sites service to manage your web sites. The API has entities that capture the relationship between an end user and the Windows Azure Web Sites service.

The Web site management API enables a core set of site administration scenarios:

  1. Create, delete, and configure web sites.

  2. Query the state of web sites.

  3. Query metrics such as resource usage, quotas, and limits.

  4. Retrieve metadata like publishing profiles.

  5. Configure the scale of web sites.

There are two main categories of end users of the Windows Azure Web Sites Management REST API:

  1. The Web site administrator creates and manages sites and supplemental resources in Windows Azure Web Sites. This role corresponds to a Windows Azure Subscription's admin or co-admin.

  2. The Publisher accesses a site’s content and publishes content by using a protocol like FTP or WebDeploy. From a hosting provider's point of view, a publisher is an FTP user. A publisher cannot perform management actions on a site.

The Windows Azure Web Sites REST API exposes the following hierarchy of resources for managing your services and deployments:

/subscriptions

   /WebSpaces

      /sites

         /config

         /publishxml

         /usages

         /metrics

         /repository

   /ServerFarm

The following table describes each of the above resources.

 

Resource Description

Subscriptions

A Windows Azure subscription is required for use of Windows Azure Web Sites.

Webspaces

A webspace is a logical entity associated with user’s subscription in a given geo region. All sites in a given region are associates of a given webspace.

Sites

A site is the core resource entity offered by the Windows Azure Web Sites service.

Config

Exposes site configuration properties like AppSettings, ConnectionStrings, Error logging, and FrameworkVersions.

Publishxml

The file in XML format that contains a user's settings for publishing a web application to Windows Azure Web Sites. This file can be imported into and used from Visual Studio or Web Matrix.

Usages

Contains information about current web site usage

Metrics

Contains historical information (reports) about usage

Repository

The source control management repository associated with site.

Serverfarm

A dedicated set of servers for hosting sites for a particular tenant in a given region. Currently, only one server farm per datacenter is supported.

New resources are created with an HTTP POST verb. The resource name is passed in the request body. If the resource is created successfully, an HTTP 201 (created) status code is returned, and the serialized resource object is included in the response body. If a client attempts to create a resource that already exists, an HTTP 409 (conflict) status code is returned.

To read the current state of an existing resource, an HTTP GET verb is used. If the resource exists, then the response status code is 200 and the response body will contain a serialized object. If the resource does not exist, then response status code is 404 (not found).

Existing resources are updated with an HTTP PUT verb. The name of the object is passed in the URL string, and the new state of the object is passed in the request body. If the resource is updated successfully, an HTTP 200 status code is returned. If the resource to be updated does not exist, an HTTP 404 (not found) status code is returned.

An existing resource is deleted with an HTTP DELETE verb. The name of the object is passed in the URL string. If the resource is deleted successfully, an HTTP 200 status code is returned. If the object has already been deleted or does not exist, then HTTP 404 is returned.

All of the Windows Azure Web Sites management APIs support two data formats: "Plain Old Xml" (POX) or JSON. The API caller can choose the format by setting the appropriate HTTP Headers in the request as follows:

 

Data Format HTTP Header

XML

"Content-Type: text/xml", "Accept: text/xml"

JSON

"Content-Type: application/json", "Accept: application/json"

Like other Windows Azure services, Windows Azure Web Sites also adheres to Windows Azure REST API versioning. Operations provided by the Windows Azure Web Sites REST API have multiple versions. You can specify which version of an operation you want to use by setting the x-ms-version request header. If you omit the x-ms-version header, the default version will be used. If your service calls an older version of an operation and a newer version exists, you can choose to continue calling the older version, or modify your code to call the newer version.

WarningWarning
If the version that you specify is deprecated, the default version will be used instead.

The x-ms-version request header value must be specified in the format YYYY-MM-DD. For example:

Request Headers:

x-ms-version: 2013-08-01

To call the Windows Azure Web Sites APIs successfully, you will need a management certificate that is associated with your subscription. For more information, see Authenticating Service Management Requests.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.