cloudant_rp.mdown

Windows Azure "ResourceProvider" Design

This doc outlines how to create a ResourceProvider to integrate Cloudant into the Microsoft Azure markertplace.

What?

Microsoft requires us to have a ResourceProvider (RP) that responds to HTTP requests, in order to mediate requests around Subscriptions and Resources.

Subscriptions are roughly analogous to a Cloudant account, while Resources equivocate to databases. The ResourceProvider must provide CRUD operations against both of these entity types. Various gotchas complicate this:

• The ResourceProvider must be able to programmatically create users, which Bisbee identified is not currently possible.
• If a Subscription identifies that it does not want marketing emails, we must exempt them from our nurture campaign(s). This is not currently possible.
• If Microsoft's specification asks us to perform an action which, under Cloudant's conception of Account and Database, is a no-op (like disabling an account), the ResourceProvider should return BAD REQUEST 400.

N.B.: "not currently possible" is not "impossible" but rather "will take effort beyond the immediate scope of this project"

How?

Through Azure, users create a subscription to Cloudant, whereupon we create an account for them and send along any credentials they'll need. When they create, modify, or delete Resources, we create, modify, or delete databases within that account. In this way, a single Azure user can have multiple Cloudant accounts.

The ResourceProvider is a webserver that receives requests from Azure, acts as directed by the spec and the request, and reports success (200), failure (500, whereupon Azure just tries again), or N/A (400).

The ResourceProvider must address the following endpoints and actions:

Subscriptions

• URL: https://:base_uri/subscriptions/:subscription_id/Events
• Method: POST

Where :base_uri is wherever the ResourceProvider lives and the URI indicated in the manifest. :subscription_id is the unique ID of the subscription. More details in the Azure docs.

The request body for these requests is an XML with a field called either EntityState or EntityEvent containing one of four values, which determines the action the ResourceProvider must take:

• Registered: Create an account.
• Disabled: Disable access to the account, but do not delete its data.
• Enabled: Restore access to the account.
• Deleted: Delete an account (though Azure recommends retaining data for 90 days, in case the account is reactivated).

Resource

• URL: https://:base_uri

Where :base_uri is wherever the ResourceProvider lives and the URI indicated in the manifest.

The ResourceProvider must handle CRUD operations for resources as follows:

• GET: Return information about the requested database.
• PUT: Create a new database.
• POST: Upgrade the specified database to a new tier of service.
• DELETE: Delete the database.

N.B. You read that right: PUT creates, POST updates. More curiously, the Resource API page says no route uses POST, but the Upgrade Resource page indicates it uses a POST. (╯°□°)╯︵ ┻━┻

Testing

The Windows Azure Resource Provider SDK provides templates in C#, Flask, and Node.js, so you don't need to write the whole thing yourself. Each comes with a test suite that proofs whether your ResourceProvider is up to snuff. Once it passes, the ResourceProvider should be ready for prime time.