[katello-devel] Subscriptions - pools - entitlements clarification | API renaming proposal

[Ivan Nečas]

Hi there,

Referencing the "[katello-devel] Activation Keys - Subscriptions - Pools 
rename" discussion we had in September, I would like to open the 
discussion about naming of subscriptions/pools/entitlements.

Taking the definition that Lukas posted here in his original post:

   subscription - what customer buys from us
   pool - list of available entitlements
   entitlement - what client consumes

So a customer buys a subscriptionl. This subscription produces a pool of 
entitlements that can be consumed. When a system subscribes to a 
product, an entitlement is assigned to it. Is it correct?

Question 1: why there is a separate concept of pools? Couldn't be the 
subscription itself used to produce entitlements? I would like to know 
the reason behind this model.

Question 2:
In our CLI there is a command:

   katello system subscriptions # List subscriptions for a system

This is the same as

   subscription-manager list # List subscription and product information 
for this machine

sub-mgr uses also the name "subscriptions" with connection to system. 
But behind the scenes it uses API

   /consumer/:consumer_id/entilements

In contrast with our CLI, that uses

   /systems/:system_id/subscriptions


To stay consistent and avoid maintenance issues later I suggest to 
rename our API to:

   /systems/:system_id/entitlements

since entitlements are the resource that the system is assigned to no 
matter what name the user calls it. I propose the same rename for the UI 
part of Katello. We would give the word "subscription" in our code base 
the same meaning as in CP.

The reason why I'm proposing this change is the fact, that I need to 
expose some API related to CP subscriptions (the customer one) and there 
is no reasonable place to add it to our controllers unless I want to mix 
it with entitlements.