Manage Subscriptions

BSS API allows managing subscriptions as described in this document.

APS Types and Operations

There are several operations that BSS exposes on the APS bus to manage subscriptions. Some of them require generating an order as considered in the Manage Orders document and the current document explains a few of other operations.

An external management system can manage a typical subscription life cycle as follows:

1. Create a subscription - place a sales order as explained in the Sales Order section of the Manage Orders document.
2. Get a list of subscriptions - there are various ways as explained in the List Subscriptions section.
3. Verify provisioning state - call the provisioningState custom operation of the subscription.
4. Get details about a subscription - this is a typical operation from the CRUD set as explained in the Get Subscription Details section.
5. Put a subscription on hold and release it from hold - call the respective custom operations as explained in the Change Subscription State section.

List Subscriptions

You can search for a subscription or a list of subscriptions using various ways as in the following examples.

• Get the full list of subscriptions:

  GET /aps/2/collections/subscriptions
  

• Get all subscriptions of a customer using the subscriptions link of the account APS type:

  GET /aps/2/resources/e5c1a984-fe7d-472e-8ffc-45e12a549b11/subscriptions
  

  The above request contains the APS ID of a customer.

• Search for a subscription using a property with a unique value, for example, search it by the internal ID assigned to the subscription in the platform:

  GET /aps/2/collections/subscriptions?eq(subscriptionId,1000016)
  

The response will look similar to the following:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://parallels.com/aps/types/pa/subscription/1.0",
         "id": "5d969e19-802b-495d-9408-2d08ca4344b7",
         "status": "aps:ready",
         ...
      },
      "description": "",
      "disabled": false,
      "name": "Cloud VPS Services",
      "trial": false,
      "serviceTemplateId": 4,
      "subscriptionId": 1000016
   },
   ...
]

If an external system needs to process a subscription bound to a certain order, get all subscriptions related to the order using the orderInfo custom operation of the order management service as explained in the Get List of Orders section of the Manage Orders document.

Verify Provisioning State

The platform may take noticeable time to create a new subscription, especially when some of the resources must be auto-provisioned. To verify if the subscription is ready, call its provisioningState custom operation, for example:

GET /aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/provisioningState

If the subscription was provisioned successfully, the response will be:

HTTP/1.1 200 OK

{
   "state": "SUCCESS",
   "message": ""
}

Get Subscription Details

To get the full representation of a subscription, use the GET method addressed to the subscription APS ID, for example:

GET /aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7

On success, the response will look similar to the following:

HTTP/1.1 200 OK

{
   "aps": {
      "schema": "/aps/2/types/98",
      "package": {
         "id": "9fb704ef-c387-4b48-95bc-c90373e51997",
         "href": "/aps/2/packages/9fb704ef-c387-4b48-95bc-c90373e51997"
      },
      "modified": "2017-12-08T16:09:39Z",
      "id": "5d969e19-802b-495d-9408-2d08ca4344b7",
      "type": "http://parallels.com/aps/types/pa/subscription/1.0",
      "status": "aps:ready",
      "revision": 6
   },
   "serviceTemplateId": 3,
   "trial": false,
   "websites": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/websites"
      }
   },
   "account": {
      "aps": {
         "link": "weak",
         "href": "/aps/2/resources/e5c1a984-fe7d-472e-8ffc-45e12a549b11",
         "id": "e5c1a984-fe7d-472e-8ffc-45e12a549b11"
      }
   },
   "disabled": false,
   "name": "Cloud VPS Services",
   "subscriptionId": 1000001,
   "description": "",
   "services": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/services"
      }
   }
}

Get Subscription Resources

To get a list of resources in a subscription, call the resources custom operation of the subscription, for example:

GET /aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/resources

On success, the response will show you all resources in the subscription:

HTTP/1.1 200 OK

[
   {
      "id": "1000105",
      "title": "Cloud VPS Services - App REF",
      "apsId": "c64796ac-4dc3-4bf1-b346-262c1910750b",
      "apsType": "http://aps-standard.org/samples/vpsdemo/cloud/1.0",
      "usage": 1,
      "limit": 1,
      "unit": "unit"
   },
   {
      "id": "1000106",
      "title": "Cloud VPS Services - Management Environment",
      "apsId": "1a99b956-397e-4531-b19a-7cdaa1017f36",
      "apsType": "http://aps-standard.org/samples/vpsdemo/context/1.0",
      "usage": 1,
      "limit": 1,
      "autoprovisioning": true,
      "unit": "unit"
   },
   {
      "id": "1000107",
      "title": "Cloud VPS Services - Virtual Server",
      "apsType": "http://aps-standard.org/samples/vpsdemo/vps/1.0",
      "usage": 0,
      "limit": 1000,
      "unit": "unit"
   }
]

Change Subscription State

The PASubscription APS type exposes two custom operations to change a subscription state.

• putOnHold - switches a subscription to the Administrative Hold state, for example:

  POST /aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/hold
  

  On success, the response is:

  HTTPS/1.1 200 OK
  

• releaseFromHold - returns a subscription to the Active state, for example:

  POST /aps/2/resources/5d969e19-802b-495d-9408-2d08ca4344b7/release
  

  On success, the response is:

  HTTPS/1.1 200 OK
  

← Manage Orders

Get Resource Consumption →