Application Packaging Standard

Last updated 18-Mar-2019

List Products¶

The generic BSS APS REST interface allows getting JSON representation of service plans and other related objects.

In this document:

APS Types
Service Plan
Notification Template
Plan Category
Resource
Service Terms
Tax Category

APS Types ¶

A service plan is a complex object presenting a product for sale and related with many other business support objects.

In the APS model, a service plan is an APS resource created from the ServicePlan APS type having relationship with other APS types.

In the diagram, the blue colored boxes (PAAccount and PAServiceTemplate) represent the APS types of the OSS platform that the service plan APS type is related with. The other boxes represent APS types exposed by BSS.

APS TYPE	APS ID	Description
Service Plan	`http://www.odin.com/billing/ServicePlan/1.0`	Cloud service product - commercial offering.
Notification Template	`http://www.odin.com/billing/NotificationTemplate/1.0`	Mail notification template in BSS used to send an event by email.
Resource	`http://www.odin.com/billing/Resource/1.0`	Resource in BSS.
Plan Category	`http://www.odin.com/billing/ServicePlanCategory/1.0`	Service Plan Category (or simply Plan Category) used to group service plans.
Service Terms	`http://www.odin.com/billing/ServiceTerms/1.0`	Service terms that determine the service deactivation process.
Tax Category	`http://www.odin.com/billing/TaxCategory/1.0`	Tax category is assigned to a group of products to involve them into a tax calculation algorithm.

Service Plan ¶

List of Service Plans¶

The ServicePlan APS type allows getting a list of all service plans or a list of service plans selected by some criteria. Usually, this is one of pre-sale operations running by the provider or resellers.

All Service Plans¶

The following request must return a list of all service plans available for the requester:

GET /aps/2/collections/service-plans

The response will look like this (details are omitted):

HTTP/1.1 200 OK

[
   {
      "aps": {...},
      "billingTerms": {...},
      "resourceRates": [],
      "longDescription": {...},
      "name": {
         "en_US": "User Management Demo"
      },
      "publication": {...},
      "shortDescription": {...},
      "subscriptionPeriods": [],
   },
   {
      "aps": {...},
      "billingTerms": {...},
      "resourceRates": [],
      "longDescription": {...},
      "name": {
         "en_US": "Resource Consumption"
      },
      "publication": {...},
      "shortDescription": {...},
      "subscriptionPeriods": [],
   },
   ...
]

List of selected Service Plans¶

It is possible to add RQL filters to narrow the list of service plans, such as the following:

Get all published service plans - the products ready for sale:

GET /aps/2/collections/service-plans?eq(publication.published,true)

Omit service plan details, for example, show only the names in English:
```
GET /aps/2/collections/service-plans?select(name.en_US)
```
Note

Anyway, the response will still contain the aps:{...} section.

Similarly to the previous, show only the names and subscription periods:

GET /aps/2/collections/service-plans?select(name.en_US,subscriptionPeriods)

Similarly, show the names and resource rates:

GET /aps/2/collections/service-plans?select(name.en_US,resourceRates)

Service Plan Details¶

If the management system knows the APS ID of a service plan, it can request its full JSON representation.

GET /aps/2/resources/314dac37-d3bd-4978-b05e-ba4658514485

The response will look like this (details are omitted):

HTTP/1.1 200 OK

{
   "aps": {...},
   "name": {...},
   "shortDescription": {...},
   "longDescription": {...},
   "subscriptionPeriods": [
      {
         "autoRenewalPeriod": {...},
         "numberOfBillingPeriods": 1,
         "trial": false,
         "defaultPeriod": false,
         "fees": {
         "setup": {
            "price": {...},
            "description": {...},
            "showZeroPrice": false
         },
         "recurring": {
            "price": {...},
            "description": {...},
            "showZeroPrice": false
         },
         "renewal": {...},
         "deposit": {...}
         },
         "refund": {...},
         "active": true
      }
   ],
   "resourceRates": [
      {
         "resourceId": "9baec2f7-2995-4527-8299-806687b148f1",
         "showInStore": true,
         "measurable": false,
         "showInCustomerPanel": true,
         "sortNumber": 999,
         "fees": {
            "setup": {...},
            "recurring": {...},
            "overuse": {...}
         },
         "publication": {...},
         "units": {...}
      },
      ...
   ],
   "billingTerms": {...},
   "publication": {...},
   "category": {...},
   "serviceTemplate": {...},
   "serviceTerms": {...},
   "vendor": {...},
   "resources": {...}
}

Notification Template ¶

BSS contains a lot of notification templates used to send notifications by email on various occasions.

List of Notification Templates¶

To get a list of all notification templates in BSS, the management system must issue the following request (below is a combined request and response):

GET /aps/2/collections/notification-templates

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/NotificationTemplate/1.0",
         "id": "f4e88d66-fbaf-407b-947b-9ac687d96f37",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-03T13:12:03Z"
      },
      "name": "Credit Memo"
   },
   ...
]

Notification Template Details¶

If the management system knows the APS ID of a notification template it can request its full JSON representation. Below is a combined request and response:

GET /aps/2/resources/f4e88d66-fbaf-407b-947b-9ac687d96f37

{
   "aps": {
      "type": "http://www.odin.com/billing/NotificationTemplate/1.0",
      "id": "f4e88d66-fbaf-407b-947b-9ac687d96f37",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-03T13:12:03Z",
      "schema": "/aps/2/types/103",
      "package": {
         "id": "4bfbda2d-8e71-45ba-b3b6-ff7a2485a178",
         "href": "/aps/2/packages/4bfbda2d-8e71-45ba-b3b6-ff7a2485a178"
      }
   },
   "name": "Credit Memo"
}

Plan Category ¶

The provider can create any number of plan categories used to group service plans for different purposes, mainly to assign them to the appropriate tax category.

List of Plan Categories¶

To get a list of all plan categories in BSS, the management system must issue the following request (below is a combined request and response):

GET /aps/2/collections/service-plan-categories

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/ServicePlanCategory/1.0",
         "id": "51487aab-2e35-4624-9077-b9252fe23f36",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-06T13:38:36Z"
      },
      "description": {
         "en_US": "Testing the integration with the Product Initialization wizard"
      },
      "name": "User Management demo"
   },
   ...
]

Plan Category Details¶

If the management system knows the APS ID of a plan category it can request its full JSON representation. Below is a combined request and response:

GET /aps/2/resources/51487aab-2e35-4624-9077-b9252fe23f36

{
   "aps": {
      "type": "http://www.odin.com/billing/ServicePlanCategory/1.0",
      "id": "51487aab-2e35-4624-9077-b9252fe23f36",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-06T13:38:36Z",
      "schema": "/aps/2/types/106",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "description": {
      "en_US": "Testing the integration with the Product Initialization wizard"
   },
   "name": "User Management demo",
   "vendor": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

Resource ¶

During application deployment, the provider creates resource types in OSS to represent the application services. Those resource types along with the service templates containing them are copied to BSS and after that are available through the BSS API considered here.

List of Resources¶

To get a list of all resources in BSS, the management system must issue the following request (below is a combined request and response):

GET /aps/2/collections/bss-resources

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/Resource/1.0",
         "id": "9baec2f7-2995-4527-8299-806687b148f1",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T14:18:26Z"
      },
      "name": {
         "en_US": "User Management demo - VPS Mainstream Profile"
      }
   },
   {
      "aps": {
         "type": "http://www.odin.com/billing/Resource/1.0",
         "id": "ebd95c84-9dc0-43dd-8ad2-bbcb4fd73374",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T14:18:26Z"
      },
      "name": {
         "en_US": "User Management demo - Virtual Server"
      }
   },
   ...
]

Resource Details¶

If the management system knows the APS ID of a resource it can request its full JSON representation. Below is a combined request and response:

GET /aps/2/resources/f4e88d66-fbaf-407b-947b-9ac687d96f37

{
   "aps": {
      "type": "http://www.odin.com/billing/Resource/1.0",
      "id": "ebd95c84-9dc0-43dd-8ad2-bbcb4fd73374",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T14:18:26Z",
      "schema": "/aps/2/types/104",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "name": {
      "en_US": "User Management demo - Virtual Server"
   }
}

Service Terms ¶

Every service plan must be bound to a service terms object.

List of Service Terms Objects¶

To get a list of all service terms in BSS, the management system must issue the following request (below is a combined request and response):

GET /aps/2/collections/service-terms

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/ServiceTerms/1.0",
         "id": "8f9da85c-7e1c-443c-bac1-074cc21c2500",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T13:53:58Z"
      },
      "destroyAfterHold": false,
      "name": "Hosting Service Terms",
      "subGracePeriod": 10,
      "subHoldPeriod": 30,
      "trialDestroyAfterHold": true,
      "trialSubGracePeriod": 0,
      "trialSubHoldPeriod": 0
   },
   ...
]

Service Terms Details¶

If the management system knows the APS ID of a service terms object it can request its full JSON representation. Below is a combined request and response:

GET /aps/2/resources/8f9da85c-7e1c-443c-bac1-074cc21c2500


{
   "aps": {
      "type": "http://www.odin.com/billing/ServiceTerms/1.0",
      "id": "8f9da85c-7e1c-443c-bac1-074cc21c2500",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T13:53:58Z",
      "schema": "/aps/2/types/107",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "destroyAfterHold": false,
   "name": "Hosting Service Terms",
   "subGracePeriod": 10,
   "subHoldPeriod": 30,
   "trialDestroyAfterHold": true,
   "trialSubGracePeriod": 0,
   "trialSubHoldPeriod": 0,
   "vendor": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

Tax Category ¶

A tax category is a very simple object that groups several service plans (through plan categories) and resources (through resource categories) to take part in a particular taxation algorithm. The algorithm takes into account the product category and the tax zone to calculate the taxes (for example, VAT) when selling those products in a particular regional zone.

List of Tax Categories¶

To get a list of all tax categories in BSS, the management system must issue the following request (below is a combined request and response):

GET /aps/2/collections/tax-categories

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/TaxCategory/1.0",
         "id": "891950fe-9a1c-46ca-aba9-8fd860cb2be8",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T13:53:59Z"
      },
      "name": "All products"
   },
   ...
]

Tax Category Details¶

If the management system knows the APS ID of a tax category it can request its full JSON representation. Below is a combined request and response:

GET /aps/2/resources/891950fe-9a1c-46ca-aba9-8fd860cb2be8

{
   "aps":
   {
      "type": "http://www.odin.com/billing/TaxCategory/1.0",
      "id": "891950fe-9a1c-46ca-aba9-8fd860cb2be8",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T13:53:59Z",
      "schema": "/aps/2/types/108",
      "package":
      {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "name": "All products",
   "vendor":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

← Using APS REST API

Manage Prices →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

List Products¶

APS Types ¶

Service Plan ¶

List of Service Plans¶

All Service Plans¶

List of selected Service Plans¶

Service Plan Details¶

Notification Template ¶

List of Notification Templates¶

Notification Template Details¶

Plan Category ¶

List of Plan Categories¶

Plan Category Details¶

Resource ¶

List of Resources¶

Resource Details¶

Service Terms ¶

List of Service Terms Objects¶

Service Terms Details¶

Tax Category ¶

List of Tax Categories¶

Tax Category Details¶

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

List Products¶

APS Types¶

Service Plan¶

List of Service Plans¶

All Service Plans¶

List of selected Service Plans¶

Service Plan Details¶

Notification Template¶

List of Notification Templates¶

Notification Template Details¶

Plan Category¶

List of Plan Categories¶

Plan Category Details¶

Resource¶

List of Resources¶

Resource Details¶

Service Terms¶

List of Service Terms Objects¶

Service Terms Details¶

Tax Category¶

List of Tax Categories¶

Tax Category Details¶

APS Types ¶

Service Plan ¶

Notification Template ¶

Plan Category ¶

Resource ¶

Service Terms ¶

Tax Category ¶