SALES: 1-800-867-1380

Web Sites Management REST API Reference

Updated: January 15, 2014

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

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

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

  • A management certificate for your 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 Azure. The management certificate must reside in the default Personal certificate store on your local computer and must also be uploaded to your Azure account. To upload a management certificate to 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 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 Azure Websites management API provides a RESTful set of web services that interact with Azure Websites service to manage your websites. The API has entities that capture the relationship between an end user and the Azure Websites service.

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

  1. Create, delete, and configure websites.

  2. Query the state of websites.

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

  4. Retrieve metadata like publishing profiles.

  5. Configure the scale of websites.

There are two main categories of end users of the Azure Websites Management REST API:

  1. The Website administrator creates and manages sites and supplemental resources in Azure Websites. This role corresponds to an 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 Azure Websites 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

An Azure subscription is required for use of Azure Websites.

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 Azure Websites 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 Azure Websites. This file can be imported into and used from Visual Studio or Web Matrix.

Usages

Contains information about current website 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. Starting with the 2014-04-01 API version, Azure Websites supports multiple server farms on each web space. You can create assign an individual billing tier for each server farm.

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 Azure Websites 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 Azure services, Azure Websites also adheres to Azure REST API versioning. Operations provided by the Azure Websites 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 Azure Websites APIs successfully, you will need a management certificate that is associated with your subscription. For more information, see Authenticating Service Management Requests.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft