Dash Management API

DASH Management API

Every DASH service exposes a WebAPI that can be used by clients to remotely manage (and in the future monitor) the Dash service. The Dash Management Portal uses this same API to perform ALL of its operations. The endpoint for the API is exposed on port 8080 of the Dash service. If the deployed Dash service includes an HTTPS endpoint, the Management API is ONLY available via HTTPS (eg. https://mydashservice.cloudapp.net:8080).

Authentication

The Management API is secured by Bearer tokens issued by Azure Active Directory. Configure Authentication for Management API describes the steps required to establish the correct configuration so that AAD authentication is enforced. Additionally, to call the API directly from a separate application you may need to include the Management API in the set of delegated resources for that application. This sample; https://github.com/Azure-Samples/active-directory-angularjs-singlepageapp-dotnet-webapi published by the AAD team fully described the required process - special attention should be applied to steps 2, 4 & 5.

Every request to the Management API MUST include the Authorization header in the format; Authorization: Bearer eyZT.....

The Management API itself requires delegated access to the Azure Service Management API. It is possible that Directory administrators may apply a policy that requires additional verification (eg. Two Factor Authentication) to be able to use this resource. This policy may only be evaluated at the time the Management API requests a delegation token to Azure and so it is possible that although the caller may have supplied a valid access token for a request, a 401 - Unauthorized response may be received. If this occurs, check for a WWW-Authorization response header in the following format:

WWW-Authorization: Bearer interaction_required={required resource} 

If an application receives this response it will have to re-logon the user and include the query parameter amr_values='mfa' to force AAD to use a multi-factor authentication flow when logging on the user.

CORS

The Dash Management API supports CORS pre-flight requests (via the OPTIONS verb) to allow all origins access to the API. This mechanism should be completely transparent to your application as all major browsers transparently support the CORS handshake for AJAX requests.

The Configuration API

The Configuration API supports the following operations:

Path	Method	Description
/configuration	GET	Fetch the current configuration from the service. Returns 200 - OK with a Configuration payload (JSON) described below.
/configuration	PUT	Update the configuration for the service. The body of the request is a JSON encoded representation of the new Configuration (described below). Returns 201 - Accepted with a JSON encoded body describing the new configuration. Note: If new Azure Storage Accounts are created by this operation, the returned configuration will include the storage keys for the new accounts.
/configuration/validate?storageAccountName=name[&storageAccountKey=key]	GET	Validate the supplied Azure Storage account information. If only the storageAccountName query parameter is supplied, then name is checked to be a valid account name and available for creation. If the storageAccountKey query parameter is supplied, then name is verified to represent an existing Azure Storage account name and key is checked to be either the primary or secondary key for that account. Returns 200 - OK with a StorageValidation payload as described below. Note that when checking the validity of an existing Storage Account name and key, the account MUST exist within the same subscription that hosts the Dash service.

Data Structures

The Configuration payload is of the following JSON format:

{
	OperationId: string,
	AccountSettings: {
		AccountName: string,
		AccountKey: string,
		SecondaryAccountKey: string,
		StorageConnectionStringMaster: storage_connection_string,
		Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString: storage_connection_string 
	},
	GeneralSettings: {
		Tenant: string,
		ClientId: guid,
		AppKey: string,
		LogNormalOperations: boolean,
		ReplicationPathPattern: regex_string,
		ReplicationMetadataName: string,
		ReplicationMetadataValue: string,
		WorkerQueueName: string
	},
	ScaleAccounts: {
		MaxAccounts: integer,
		Accounts:[{
			AccountName: string,
			AccountKey: string
		}]
	}
}

where:

Attribute Name	Description
OperationId	The identifier for any ongoing operation. If the response for a GET operation includes this attribute, then an update operation is already in progress. In response to a PUT operation this value is the identifier for the update operation initiated by this request. This value may be specified in calls to the /operations/index/OperationId API.
AccountName	The name of the account used to sign every storage request as per the standard Azure Storage protocol (Authentication for the Azure Storage Services). For a standard Azure Storage account this name is also the DNS prefix. Eg. mystorageaccount is mystorageaccount.blob.core.windows.net. For Dash, there is no correlation between the DNS name and the account name.
AccountKey & SecondaryAccountKey	This is the key that will be used to construct the signature authenticating every storage request as per the standard Azure Storage protocol. Two keys are available in the same manner as a standard Storage Account so that you can 'roll over' keys without having application outages. This value should be a base64 encoded representation of at least 64 bytes of random data to be sufficiently diverse as to not be crackable.
StorageConnectionStringMaster	This is the connection string (in any acceptable Azure Storage format) used to identify and connect to the namespace storage account. If the connection string has no value for the AccountKey= section a new Azure Storage account will be created in the same subscription and region as the Dash service.
Microsoft...Diagnostics.ConnectionString	This is the connection string specifying the Azure Storage account where diagnostic information (IIS Logs, Trace Logs, Performance Counters) will be copied to from each Dash instance. If the connection string has no value for the AccountKey= section a new Azure Storage account will be created in the same subscription and region as the Dash service.
Tenant	The AAD tenant (guid or DNS name) used to authenticate to the Management API.
ClientId	The Client ID value of the AAD Application to authenticate to the Management API.
AppKey	The Key that matches an available key in the AAD Application to authenticate to the Management API.
LogNormalOperations	If true every operation to Dash will be logged in the Trace Log. If false (default) only operations that have a non-successful result will be logged.
ReplicationPathPattern	This is a regular expression that will be used to match against blob names to determine if the blob should be replicated. If blank no blob name matching will be evaluated.
ReplicationMetadataName	Specifies the metadata name that if applied to a blob (with a value that matches the ReplicationMetadataValue attribute) will cause the blob to be replicated. If blank or omitted no blob metadata will be checked for replication of the blob.
ReplicationMetadataValue	If a blob contains a metadata attribute that matches the ReplicationMetadataName with a value that matches this attribute, the blob will be replicated for read scalability.
WorkerQueueName	Allows to override the default name of the Azure Storage Queue that holds all asynchronous operations for the Dash service. If omitted or blank, the default value is; dashworkerqueue.
MaxAccounts	The maximum number of Azure Storage accounts that can be included as data accounts. If there is no maximum limit, this value will be omitted or -1.
Accounts	An array of connection information representing the data accounts. If the number of elements in this array is less than the MaxAccounts attribute, additional accounts may be added. Existing accounts may not be altered (other than updating the AccountKey value) or removed from this array as it will lead to data loss. When an existing Azure Storage account is added to this array, the existing contents will be 'imported' into the Dash virtual account. This involves asynchronously scanning the entire contents of the account and creating associated namespace entries. No data is moved during this import process.
AccountName	The name of the data account. Depending on the value of the AccountKey attribute, this account name must either already exist or be a valid name for creation. If the account is to be created it will be added to the same subscription that hosts the Dash service and in the same region. If the account already exists, there is no requirement on the subscription or location (although there will be performance impacts of not co-locating accounts) of this account. Call the /configuration/validate API to determine the validity of this value PRIOR to calling the PUT operation.
AccountKey	The primary or secondary key to be used to connect to an existing data account. If this attribute is blank or missing the PUT operation will assume that a new account is to be created. Upon return, this attribute will be populated with the primary key of the newly created account. Call the /configuration/validate API to determine the validity of this value PRIOR to calling the PUT operation.

The StorageValidation payload is of the following JSON format:

{
	NewStorageNameValid: boolean,
	ExistingStorageNameValid: boolean,
	StorageKeyValid: boolean
}

where:

Attribute Name	Description
NewStorageNameValid	Indicates if name is a valid value for a new Azure Storage account.
ExistingStorageNameValid	Indicates if name represents the name of an existing Azure Storage account.
StorageKeyValid	Indicates if key is a valid key to connect to the existing Azure Storage account.

The Update API

The Update API supports the following operations:

Path	Method	Description
/update/available	GET	Determine if a software update is available for the Dash service. Returns 200 - OK with a AvailableUpgrade response. This is the only API call that may be called without a valid bearer token in the Authorization header.
/update	GET	Fetch a list of details for all software updates available for the Dash service. Returns 200 - OK with a UpgradePackages response.
/update	POST	Initiate a software update operation for the Dash service. The request body is a JSON encoded UpdateVersion structure. Returns 201 - Accepted with a OperationResult response on success.

Data Structures

The AvailableUpgrade payload is of the following JSON format:

{
	AvailableUpdate: boolean,
	HighestSeverity: 'Optional' | 'Important' | 'Critical',
	UpdateVersion: string
}

where:

Attribute Name	Description
AvailableUpdate	Indicates if a software update is available for the Dash service.
HighestSeverity	The highest severity level of all available updates for the Dash service.
UpdateVersion	The highest version number available to update the Dash service.

The UpgradePackages payload is of the following JSON format:

{
	CurrentVersion: string,
	AvailableUpdates: [{
		Version: string,
		Description: string,
		Severity: 'Optional' | 'Important' | 'Critical'
	}]
}

where:

Attribute Name	Description
CurrentVersion	The version string of the currently running software on the Dash service.
AvailableUpdates	An array of updates available to be applied to the Dash service
Version	The version string identifying an available update. This value may be specified in the UpdateVersion structure of the /update API.
Description	An HTML string describing new features & bugfixes included in the update.
Severity	An enumerated string indicating the importance of the update.

The UpdateVersion payload is of the following JSON format:

{
	version: string
}

where:

Attribute Name	Description
version	The version number (taken from the UpgradePackages.AvailableUpdates.Version structure) that the Dash service should be upgraded to.

The OperationResult payload is of the following JSON format:

{
	OperationId: string,
	ErrorCode: string,
	ErrorMessage: string,
}

where:

Attribute Name	Description
OperationId	The identifier for the asynchronous operation. This value may be specified in calls to the /operations/OperationId API.
ErrorCode	If the operation has failed, this is the code returned by the Azure service fabric describing the failure.
ErrorMessage	If the operation has failed, this is the description returned by the Azure service fabric for the failure.

The Operation Status API

The Operation Status API supports the following operations:

Path	Method	Description
/operations/OperationId	GET	Returns status information for the operation identified by OperationId (returned from a variety of other asynchronous API calls). Returns 200 - OK with a OperationState response on success.

Data Structures

The OperationState payload is of the following JSON format:

{
	Id: string,
	Status: 'NotStarted' | 'InProgress' | 'Succeeded' | 'Failed',
	Message: string
}

where:

Attribute Name	Description
Id	The identifier for this asynchronous operation.
Status	One of the listed enumeration of values indicating the state of the operation.
Message	Descriptive information for the state of the operation. If Status == 'InProgress' this attribute will describe the last operation attempted. If Status == 'Failed' this will be the reason for the failure.