Windows Azure Pack Websites Service REST API
Applies To: Windows Azure Pack
This documentation describes how to perform common tasks in web sites by using the Windows Azure Pack Web Sites management REST API.
Overview
The Windows Azure Pack Web Sites management API provides a RESTful set of web services that interact with the Windows Azure Pack Web Sites service to manage your websites. The API has entities that capture the relationship between an end user and the Windows Azure Pack Web Sites service.
The Web Sites management API enables a core set of site administration scenarios:
Create, delete, and configure websites.
Query the state of websites.
Query metrics such as resource usage, quotas, and limits.
Retrieve metadata such as publishing profiles.
Configure the scale of websites.
End Users
There are two main categories of end users of the Windows Azure Pack Web Sites Management REST API:
The Web site administrator creates and manages sites and supplemental resources in Windows Azure Pack Web Sites. This role corresponds to a Windows Azure Pack Subscription's administrator or co-administrator.
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.
Resources
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 the preceding resources.
Resource |
Description |
|---|---|
Subscriptions |
A Windows Azure Pack subscription that is required for use of Windows Azure Web Sites. |
Webspaces |
A webspace that is a logical entity, which is associated with user’s subscription in a given geographical region. All sites in a given region are associates of a given webspace. |
Sites |
A site that is the core resource entity, which is offered by the Windows Azure Web Sites service. |
Config |
A resource that contains site configuration properties such as AppSettings, ConnectionStrings, ErrorLogging, and FrameworkVersions. |
Publishxml |
The file in XML format that contains a user's settings to publish a web application to Windows Azure Web Sites. This file can be imported into and used from Microsoft Visual Studio or Web Matrix. |
Usages |
A resource that contains information about current website usage. |
Metrics |
A resource that contains historical information in reports about usage. |
Repository |
The source control management repository that is associated with the site. |
Serverfarm |
A set of computers that are reserved for hosting sites for a particular tenant in a given region. Currently, only one server farm per data center is supported. |
Operations on Resources
Creating a resource
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 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.
Reading a resource
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 contains a serialized object. If the resource does not exist, then the response status code is 404, the resource was not found.
Updating a resource
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.
Deleting a resource
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.
API Versioning
Like Windows Azure services, Windows Azure Pack Web Sites adhere to Windows Azure REST API versioning. Operations provided by the Windows Azure Pack Web Sites REST API have multiple versions. You must specify which version of an operation you want to use by setting the x-ms-version request header. Requests without an x-ms-version header are rejected and return a (400) Bad Request response. If your service calls a previous version of an operation and a newer version exists, you can choose to continue calling the previous version or continue to modify your code to call the newer version.
Note
Although API versions can change, Windows Azure Pack Web Sites supports both the newer API version and the immediately previous version.
The x-ms-version request header value must be specified in the format YYYY-MM-DD. The code example shows the required format.
Request Headers:
x-ms-version: 2012-10-10