You can use cURL commands to create and manage a subscriptions with the CURL HTTP client.

Create a Subscription

The API operation that creates a subscription is: POST /subscriptions

The following Linux shell script sends a POST /subscriptions/ and waits for a cloud account ID. When the cloud account ID is received, the processing phase is complete and the provisioning phase starts.

Prerequisites

  • Install jq on your machine: sudo apt install jq
  • Define the expected variables needed to use the API:

export HOST=api.redislabs.com/v1
export ACCOUNT_KEY={replace-with-your-account-key}
export SECRET_KEY={replace-with-your-secret-key}

Subscription JSON body

The created subscription is defined by a JSON document that is sent as the body of the POST subscriptions request.

In the example below, that JSON document is stored in the create-subscription-basic.json file:


{
    "name": "Basic subscription example",
    "paymentMethodId": 8240,
    "cloudProviders": [
      {
        "cloudAccountId": 9838,
        "regions": [
          {
            "region": "us-east-1",
            "networking": {
              "deploymentCIDR": "10.0.0.0/24"
            }
          }
        ]
      }
    ],
    "databases": [
      {
        "name": "Redis-database-example",
        "memoryLimitInGb": 1.1
      }
    ]
}

Subscription creation script

You can run the create subscription script from the command line with: bash path/script-name.sh

Below is the sample script that you can use as a reference to call the API operation to create a subscription. The script contains the steps that are explained below.


echo "Step 1: Post a request to create a subscription"

TASK_ID=$(curl -s -X POST "https://$HOST/subscriptions" \
    --header "Content-Type: application/json" \
    -H "accept: application/json" \
    -H "x-api-key: $ACCOUNT_KEY" \
    -H "x-api-secret-key: $SECRET_KEY" \
    --data-binary "@./static/code/rv/api/create-subscription-basic.json" \
    | jq -r .taskId )

echo "TASK_ID=$TASK_ID"


echo "Step 2: wait for processing completion"

STATUS=received
while [ "$STATUS" == "processing-in-progress" ] || [ "$STATUS" == "received" ]
do
    sleep 3 # seconds   
    STATUS=$(curl -s -X GET "https://$HOST/tasks/$TASK_ID" \
    -H "accept: application/json" \
    -H "x-api-key: $ACCOUNT_KEY" \
    -H "x-api-secret-key: $SECRET_KEY" \
    | jq -r .status)
    echo "STATUS=$STATUS"
done

echo "Step 3: print the response, containing the created resource Id / error" 

echo "Response: "
curl -s -X GET "https://$HOST/tasks/$TASK_ID" \
    -H "accept: application/json" \
    -H "x-api-key: $ACCOUNT_KEY" \
    -H "x-api-secret-key: $SECRET_KEY" \
    | jq -r .

Step 1 of the subscription creation script

This step executes a POST request to subscriptions with the defined parameters and a JSON body located within a separate JSON file.

The POST response is a JSON document that contains the taskId, which is stored in a variable called TASK_ID that is used later to track the progress request.

Step 2 the subscription creation script

This step queries the API for the status of the subscription creation request based on the taskId stored in the $TASK_IS variable.

Step 3 the subscription creation script

When the status changes from processing-in-progress to processing-completed (or processing-error), this step prints the response, including the resourceId. In this case the resourceId is a subscription ID.

If the processing phase completed successfully, the subscription is visible in the Redis Labs management site in the pending status. This status indicates that the subscription is being provisioned.

You can use the GET /subscriptions/{subscriptionId} API operation to track the created subscription until it changes to the active state.

Additional subscription parameters

To use the sample JSON document in your own account, you must modify these parameters:

  • paymentMethodId - Specify a payment method that is defined for your account. You can lookup the payment method identifier using the GET /payment-methods API operation.
  • cloudAccountId - Specify a cloud account that is defined for your account. You can lookup the cloud accounts identifiers using the GET /cloud-accounts API operation or use "cloudAccountId": 1 to use Redis Labs internal resources.
  • The JSON document contains 2 primary segments: subscription specification and databases specification.
  • When you create a subscription, you must specify one or more databases in the "databases" array of the above JSON file.
  • You can copy-and-paste the contents of the JSON file into the POST /subscriptions operation in the Swagger UI.
Note -
The Swagger UI generates default JSON examples for POST and PUT operations. You can reference these examples and modify them to fit your specific needs and account settings. The examples will fail if used as-is.