Azure DocumentDB Resource Provider REST API Referencedownload.microsoft.com/download/3/D/9/3D9AE276-3F76-45F2-843… · Introduction . This document contains reference material for

documentdb.com Azure DocumentDB Resource Provider REST API 1

Azure DocumentDB Resource Provider REST API Reference Last updated: December 21st, 2016


Contents Introduction .................................................................................................................................................. 4

Versioning ................................................................................................................................................. 4

Authorization token .................................................................................................................................. 4

Azure DocumentDB Resource Provider Operations ..................................................................................... 4

Create or Update DocumentDB Account ...................................................................................................... 4

Request ..................................................................................................................................................... 4

Response ................................................................................................................................................... 6

Delete DocumentDB Account ....................................................................................................................... 8

Request ..................................................................................................................................................... 8

Response ................................................................................................................................................... 8

Modifying Failover Priorities ......................................................................................................................... 9

Response ................................................................................................................................................. 10

Get DocumentDB Account Properties ........................................................................................................ 11

Request ................................................................................................................................................... 11

Response ................................................................................................................................................. 11

List DocumentDB Accounts for Subscription .............................................................................................. 15

Request ................................................................................................................................................... 15

Response ................................................................................................................................................. 15

List DocumentDB Accounts for Resource Group ........................................................................................ 17

Request ................................................................................................................................................... 17

Response ................................................................................................................................................. 17

Get DocumentDB Account Keys .................................................................................................................. 20

Request ................................................................................................................................................... 20

Response ................................................................................................................................................. 20

Get DocumentDB Account Read Only Keys ................................................................................................ 21

Request ................................................................................................................................................... 21

Response ................................................................................................................................................. 22

Regenerate DocumentDB Account Keys ..................................................................................................... 22

Request ................................................................................................................................................... 22

Response ................................................................................................................................................. 24


Check DocumentDB Account Name Availability ......................................................................................... 24

Request ................................................................................................................................................... 24

Response ................................................................................................................................................. 25

Appendix A .................................................................................................................................................. 25

1.1 Management API – request headers .......................................................................................... 25

1.2 Management API – response headers ........................................................................................ 26


Introduction This document contains reference material for the Azure DocumentDB Resource Provider, which enables you to manage your DocumentDB account and keys programmatically, via the REST API. For information on managing databases, collections, and documents via REST, see Azure DocumentDB REST API. For additional documentation for DocumentDB, see DocumentDB documentation.

Versioning The DocumentDB Resource Provider requires all requests to be versioned. To make a request, you must specify the version that you want to use for that operation. The currently supported version is 2015-05-08.

Authorization token All Azure Resource Manager REST calls require a valid authorization token in the request header to succeed. Visit: Authenticating Azure Resource Manager requests for details on how to obtain this authorization token.

Azure DocumentDB Resource Provider Operations

Create or Update DocumentDB Account The Create or Update DocumentDB Account operation creates a new DocumentDB account with the specified parameters. If an account was already created and a subsequent PUT request is issues with different properties, then the account will be updated. This can also be used to Add/Remove regions within the database account. Create a resource group via the portal.

Request Request URI

Method Request URI

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}?api-version={api-version}

Request URI Parameters Parameter Description

subscriptionId The subscriptionId for the Azure user.

resourceGroupName The name of the resource group within the user’s subscription.

accountName The name of the DocumentDB account within the specified resource group.

api-version Specifies the version of the protocol used to make this request. The currently supported version is 2015-04-08.

Request Headers

https://azure.microsoft.com/services/documentdb/

https://go.microsoft.com/fwlink/?LinkId=402413&clcid=0x409

https://go.microsoft.com/fwlink/?LinkId=402413&clcid=0x409

https://go.microsoft.com/fwlink/?linkid=834756

https://msdn.microsoft.com/en-us/library/azure/dn790557.aspx


Header Description

Content-type Set this header to application/json. Required

x-ms-client-request-id

Caller-specified request ID, in the form of a GUID with no decoration such as curly braces. If specified, this will be included in response information as a way to map the request.

Optional

x-ms-return-client-request-id

True or false. Indicates if a client-request-id should be returned in the response. Optional

Accept-Language Specifies the preferred language for the response when generating error messages Optional

Request Body { "location": "West US", "tags": { "key": "value" }, "properties": { "databaseAccountOfferType": "Standard", "consistencyPolicy": { "defaultConsistencyLevel": "Eventual|Session|BoundedStaleness|Strong", "maxStalenessPrefix": 100, "maxStalenessIntervalInSeconds": 10 }, "ipRangeFilter": "", "locations": [ { "locationName": "West US", "failoverPriority": 0 }, { "locationName": "East US", "failoverPriority": 1 } ] } } Request Body Parameters Header Description

location The location of the resource group. This will be one of the supported and registered Azure regions. Required

locationName Locations where the database account should exist. This will be one of the supported and registered Azure Geo Regions.

Required


failoverPriority

One of the regions must have a failoverPriority value of 0 to indicate that this region be kept as the write region for the DocumentDB account. The failover priority values must be unique amongst the locations and the highest failover priority value must be less than the total number of regions. If updating a database account, match the failover priority values to the existing configuration.

Required

databaseAccountOfferType This value should be set to “Standard”. Required

tags

A list of key value pairs that describe the resource. These tags can be used in viewing and grouping this resource (across resource groups). A maximum of 15 tags can be provided for a resource. Each tag must have a key no greater than 128 characters and value no greater than 256 characters.

Optional

defaultConsistencyLevel Sets the default consistency level and configuration settings for a DocumentDB account. Optional

maxStalenessPrefix When used with Bounded Staleness consistency, this value represents the number of stale requests tolerated. Accepted range for this value is 1 – 2,147,483,647.

Optional

maxStalenessIntervalInSeconds When used with Bounded Staleness consistency, this value represents the time amount of staleness (in seconds) tolerated. Accepted range for this value is 1 - 100.

Optional

ipRangeFilter Used to configure the firewall for the database account. Specifies the set of IP addresses or IP address ranges in classless inter-domain routing (CIDR) form to be included as the allowed list of client IPs for a given database account. IP addresses/ranges must be comma separated and must not contain any spaces.

Optional

Response The response includes an HTTP status code, a set of response headers, and a response body. Status Code 200 (OK) returned to indicate that the operation will complete asynchronously. 400 (Bad Request) is returned when the request contains malformed syntax. 403 (Forbidden) is returned if the requested Is not authorized to create this resource in the subscription or resource group 404 (NotFound) is returned when the subscription or the resource group does not exist


Response Headers Header Description

Content-Location The URI of the request.

Content-Type Content-Type Set to application/json. This header is not required in responses that don’t have any content.

x-ms-request-id A unique identifier for the current operation, service generated.

Response Body { "id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DocumentDB/databaseAccounts/<accountName>", "name": "<accountName>", "location": "West US", "type": "Microsoft.DocumentDB/databaseAccounts", "kind": "GlobalDocumentDB", "tags": {}, "properties": { "provisioningState": "Initializing", "databaseAccountOfferType": "Standard", "ipRangeFilter": "", "consistencyPolicy": { "defaultConsistencyLevel": "Eventual|Session|BoundedStaleness|Strong", "maxIntervalInSeconds": 5, "maxStalenessPrefix": 100 } } } The “provisioningState” property in the response header indicates the state of the operation.


Delete DocumentDB Account The Delete DocumentDB Account operation deletes an existing DocumentDB account in Microsoft Azure.

Request Request URI

Method Request URI

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}?api-version={api-version}






Request Headers Header Description



Optional



Accept-Language Specifies the preferred language for the response when generating error messages. Optional

Request Body Empty Response Response Status Code HTTP 202 (Accepted) if the operation is successful HTTP 204 (NoContent) if the account does not exist in the subscription Response Headers


Header Description

x-ms-request-id A unique identifier for the current operation, service generated. Response Body { "status": "Enqueued", "error": {} }

Modifying Failover Priorities The DocumentDB REST API also allows developers to programmatically modify the failover priorities of the regions within the database account. Note: changing the write region (failover priority = 0) causes a failover to occur.

Method Request URI

POST https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DocumentDB/databaseAccounts/<accountName>/failoverPriorityChange?api-version=2015-04-08

Parameter Description





Date The date that the request was processed in RFC 1123 format.


Request Body { "failoverPolicies": [ { "locationName": "West US", "failoverPriority": 1 }, { "locationName": "East US", "failoverPriority": 0 } ]

https://management.azure.com/subscriptions/%3csubscriptionId%3e/resourceGroups/%3cresourceGroupName%3e/providers/Microsoft.DocumentDB/databaseAccounts/%3caccountName%3e/failoverPriorityChange?api-version=2015-04-08




} Response Response Status Code HTTP 202 (Accepted) if the operation is successful HTTP 400 (Bad Request) if the request contains invalid data Response Headers Header Description


x-ms-request-id A unique identifier for the current operation, service generated. Response Body { "status": "Enqueued", "error": {} }


Get DocumentDB Account Properties The Get DocumentDB Account Properties operation returns the properties for the specified DocumentDB account including but not limited to name, account type, location, and account status. The Get DocumentDB Account Keys operation should be used to retrieve DocumentDB account keys.

Request Request URI

Method Request URI

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}?api-version={api-version}









Optional




Request Body Empty

Response Response Status Code HTTP 200 (OK) if successful HTTP 404 (NotFound) if the account does not exist




x-ms-request-id A unique identifier for the current operation, service generated. Response Body { "id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DocumentDB/databaseAccounts/<accountName>", "name": "<accountName>", "location": "West US", "type": "Microsoft.DocumentDB/databaseAccounts", "kind": "GlobalDocumentDB", "tags": {}, "properties": { "provisioningState": "Succeeded", "documentEndpoint": "https://<accountName>.documents.azure.com:443/", "databaseAccountOfferType": "Standard", "consistencyPolicy": { "defaultConsistencyLevel": "Eventual|Session|BoundedStaleness|Strong", "maxIntervalInSeconds": 5, "maxStalenessPrefix": 100 }, "ipRangeFilter": "", "writeLocations": [ { "id": "<accountName>-eastus", "locationName": "East US", "documentEndpoint": "https://<accountName>-eastus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 } ], "readLocations": [ { "id": "<accountName>-eastus", "locationName": "East US", "documentEndpoint": "https://<accountName>-eastus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 }, { "id": "<accountName>-westus", "locationName": "West US", "documentEndpoint": "https://<accountName>-westus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 1 } ],


"failoverPolicies": [ { "id": "<accountName>-eastus", "locationName": "East US", "failoverPriority": 0 }, { "id": "<accountName>-westus", "locationName": "West US", "failoverPriority": 1 } ] } }

Response Body Elements Element Description

id The id is the URL (excluding the hostname/scheme) for the DocumentDB account. See the Request URI parameters table for details on the bracketed fields.

name The name of the DocumentDB account.

type Resource Type.

location The location of the resource. This will be one of the supported and registered Azure Geo Regions (e.g. West US, East US, Southeast Asia, etc.).

kind Indicates the type of DocumentDB account: either ‘DocumentDB’, ‘MongoDB’, or ‘Parse’.

tags Tags are a list of key value pairs that describe the resource. These tags can be used in viewing and grouping this resource (across resource groups).

provisioningState The status of the DocumentDB account at the time the operation was called. Can be one of:

• Creating – the DocumentDB account is being created. When an account is in “Creating” state, only properties that are specified as input for the Create DocumentDB Account operation are returned.

• Succeeded – the DocumentDB account is active for use • Updating – the DocumentDB account is being updated • Deleting – the DocumentDB account is being deleted • Failed – the DocumentDB account failed creation

databaseAccountOfferType The offer type for the DocumentDB database account. Default value: Standard.

defaultConsistencyLevel The default consistency level and configuration settings of the DocumentDB account.


maxStalenessPrefix When used with Bounded Staleness consistency, this value represents the number of stale requests tolerated. Accepted range for this value is 1 – 2,147,483,647.

maxStalenessIntervalInSeconds When used with Bounded Staleness consistency, this value represents the time amount of staleness (in seconds) tolerated. Accepted range for this value is 1 - 100.

ipRangeFilter Used to configure the firewall for the database account. Specifies the set of IP addresses or IP address ranges in CIDR form to be included as the allowed list of client IPs for a given database account. IP addresses/ranges must be comma separated and must not contain any spaces.

documentEndpoint The endpoint the used to access the DocumentDB account.

writeLocations An array which consists of the write location for the DocumentDB account.

readLocations An array which consists of the read locations enabled for the DocumentDB account.

failoverPolicies

An array which consists of the regions ordered by their failover priorities.


List DocumentDB Accounts for Subscription The List DocumentDB Accounts operation lists all the DocumentDB accounts under the subscription. Note that DocumentDB account keys are not returned, use the Get DocumentDB Account Keys operation for this.

Request Request URI

Method Request URI

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/databaseAccounts?api-version={api-version}

Request URI Parameters Argument Description






Optional




Request Body Empty Response Response Status Code HTTP 200 (OK) if successful Response Headers Header Description




Response Body Formatted list of DocumentDB accounts and their properties. { "value": [ { "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}", "name": "testDatabaseAccount", "type": "Microsoft.DocumentDB/databaseaccount/", "location": "West US", "kind": "DocumentDB", "tags": { "key1": "value 1", "key2": "value 2" }, "properties": { "provisioningState": "Succeeded", "databaseAccountOfferType": "Standard", "consistencyPolicy": { "defaultConsistencyLevel": "Session", "maxIntervalInSeconds": 5, "maxStalenessPrefix": 100 }, "ipRangeFilter": "", "documentEndpoint": "testDatabaseAccount.documents.windows.net", "writeLocations": [ { "id": "testDatabaseAccount-westus", "locationName": "West US", "documentEndpoint": "https://testDatabaseAccount-westus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 } ], "readLocations": [ { "id": "testDatabaseAccount-westus", "locationName": "West US", "documentEndpoint": "https://testDatabaseAccount-westus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 } ], "failoverPolicies": [ { "id": "testDatabaseAccount-westus", "locationName": "West US", "failoverPriority": 0 } ] } } ]


}

List DocumentDB Accounts for Resource Group The List DocumentDB Accounts operation lists all the DocumentDB accounts under the given reousrce group. Note that DocumentDB account keys are not returned, use the Get DocumentDB Account Keys operation for this.

Request Request URI

Method Request URI

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts?api-version={api-version}

Request URI Parameters Argument Description


resourceGroupName The resource group name uniquely identifies the resource group within the user subscriptionId.





Optional




Request Body Empty Response Response Status Code HTTP 200 (OK) if successful




x-ms-request-id A unique identifier for the current operation, service generated. Response Body Formatted list of DocumentDB accounts and their properties. { "value": [ { "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}", "name": "testDatabaseAccount", "type": "Microsoft.DocumentDB/databaseaccount/", "location": "West US", "kind": "DocumentDB", "tags": { "key1": "value 1", "key2": "value 2" }, "properties": { "provisioningState": "Succeeded", "databaseAccountOfferType": "Standard", "consistencyPolicy": { "defaultConsistencyLevel": "Session", "maxIntervalInSeconds": 5, "maxStalenessPrefix": 100 }, "ipRangeFilter": "", "documentEndpoint": "testDatabaseAccount.documents.windows.net", "writeLocations": [ { "id": "testDatabaseAccount-westus", "locationName": "West US", "documentEndpoint": "https://testDatabaseAccount-westus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 } ], "readLocations": [ { "id": "testDatabaseAccount-westus", "locationName": "West US", "documentEndpoint": "https://testDatabaseAccount-westus.documents.azure.com:443/", "provisioningState": "Succeeded", "failoverPriority": 0 } ], "failoverPolicies": [ {


"id": "testDatabaseAccount-westus", "locationName": "West US", "failoverPriority": 0 } ] } } ] }


Get DocumentDB Account Keys The List Keys operation returns the read-write and read-only access keys for the specified DocumentDB account.

Request Request URI

Method Request URI

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/listKeys?api-version={api-version}



subscriptionId The subscriptionID for the Azure user.

resourceGroupName The name of the resource group within the user’s subscriptionID.

accountName The name of the DocumentDB account within the specified resource stack.


listKeys Action. Retrieves the master read-write and read-only access keys for the database account.

Request Headers None

Request Body Empty

Response Response Status Code

200 (OK) if successful. Response Headers

Header Description




Response Body

{ “primaryMasterKey”: “primary read-write key value”, “secondaryMasterKey”: “secondary read-write key value”, “primaryReadonlyMasterKey”: “primary read-only key value”, “secondaryReadonlyMasterKey”: “secondary read-only key value”

}

Response Body Elements

Element Description

primaryMasterKey The primary read-write access key for the DocumentDB account. Only full admin will see this key.

secondaryMasterKey The secondary read-write access key for the DocumentDB account. Only full admin will see this key.

primaryReadonlyMasterKey The primary read-only access key for the DocumentDB account.

secondaryReadonlyMasterKey The secondary read-only access key for the DocumentDB account.

Get DocumentDB Account Read Only Keys The Read Only Keys operation returns the primary and secondary read only keys for the specified DocumentDB account. The read only keys are for read only admins to read resources in database. Users and permissions are not accessible to read only admins.

Request Request URI

Method Request URI

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/readonlykeys?api-version={api-version}



resourceGroupName The name of the resource group within the user’s subscriptionID.




readonlykeys Action. Retrieves the primary and secondary read-only keys for the database account.

Request Headers None

Request Body Empty


200 (OK) if successful. Response Headers

Header Description



Response Body

{

“primaryReadonlyMasterKey”: “primary read-only key value”, “secondaryReadonlyMasterKey”: “secondary read-only key value”

}

Response Body Elements

Element Description

primaryReadonlyMasterKey The primary read-only access key for the DocumentDB account.

secondaryReadonlyMasterKey The secondary read-only access key for the DocumentDB account.

Regenerate DocumentDB Account Keys The Regenerate Keys operation regenerates the primary or secondary keys for the specified DocumentDB account.

Request Request URI


Method Request URI

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/regenerateKey?api-version={api-version}



resourceGroupName The name of the resource stack within the user’s subscriptionID.



regenerateKey Action. Specifies which access key must be regenerated.





Optional




Request Body

{

"keyKind": "primary|secondary|primaryReadonly|secondaryReadonly"

}

Request Body Parameters

Parameter Description

keyKind Specifies which key should be regenerated. Required



HTTP 202 (Accepted) if successful.

Response Headers

Header Description



Response Body

None.

Check DocumentDB Account Name Availability The Check DocumentDB Account Name Availability operation checks that an account name is valid and is not already in use.

Request Request URI

Method Request URI

HEAD https://management.azure.com/providers/Microsoft.DocumentDB/databaseAccountNames/{accountName}?api-version={api-version}


accountName The name of the database account being checked for validity and availability.

api-version Version of the API to be used with the client request. The current version is 2015-04-08.

Request Headers

Header Description





Optional




Request Body

None

Request Body Parameters

None


HTTP 200 (OK) if account name is valid but unavailable (already in use). HTTP 404 (Not Found) if account name is valid and available. HTTP 400 (Bad Request) if account name is invalid.

Response Headers

Header Description



Response Body

None

Appendix A

1.1 Management API – request headers The following are the common request headers for Resource Provider API.


Header Description

Content-Type Set to application/json. This header is not sent in requests that don’t have any content, such as all GET calls.

Accept-Language Specifies the preferred language for the response; all resource providers should use this header when generating error messages or client facing text.

x-ms-client-request-id Optional. A caller-defined value that identifies the given request in the form of a GUID with no decoration such as curly braces (e.g. client-request-id: 9C4D50EE-2D56-4CD3-8152-34347DC9F2B0). If specified, this will be included in response information as a way to map the request.

x-ms-return-client-request-id Optional. True or false, indicates whether a client-request-id should be provided.

1.2 Management API – response headers All responses will include the following headers:

Header Description

Content-Type Set to application/json. This header is not required in responses that don’t have any content.

Content-Location The URI of the request.

Date The date that the request was processed, in RFC 1123 format.


©2016 Microsoft Corporation. All rights reserved.

This document is provided “as-is.” Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it. This document does not provide you with any legal rights to any intellectual property in any Microsoft product.

Documents

Azure DocumentDB Resource Provider REST API Referencedownload.microsoft.com/download/3/D/9/3D9AE276-3F76-45F2-843… · Introduction . This document contains reference material for