[Engine-devel] planned changes for api capabilities resource
the motivation: =============== 1. current design is not restfull 2. is not consistent with the rest of api impl. impacts: ======== as this resource not used programmatically, we do not expect any backward compatibility issues planned change is: ================= from: http://localhost:8080/api/capabilities <capabilities> <version major="3" minor="1"> ... <version/> <version major="3" minor="0"> ... <version/> </capabilities> to: http://localhost:8080/api/capabilities/xxx <capabilities> ... </capabilities> (where xxx is a version number) -- Michael Pasternak RedHat, ENG-Virtualization R&D
Hi Michael, two questions: Can you elaborate on why you think there's no backwards compatibility issues? In your proposal, are you leaving /api/capabilites in place as it is now? If not how to you enumerate the different versions? Regards, Geert On 05/24/2012 09:53 AM, Michael Pasternak wrote:
the motivation: ===============
1. current design is not restfull 2. is not consistent with the rest of api impl.
impacts: ========
as this resource not used programmatically, we do not expect any backward compatibility issues
planned change is: =================
from:
http://localhost:8080/api/capabilities
<capabilities> <version major="3" minor="1"> ... <version/> <version major="3" minor="0"> ... <version/> </capabilities>
to:
http://localhost:8080/api/capabilities/xxx
<capabilities> ... </capabilities>
(where xxx is a version number)
-- Geert Jansen Sr. Product Marketing Manager, Red Hat Enterprise Virtualization Red Hat S.r.L. O: +39 095 916287 Via G. Fara 26 C: +39 348 1980079 (when in US: 415-623-0542) Milan 20124, Italy E: gjansen@redhat.com
On 05/29/2012 10:56 AM, Geert Jansen wrote:
Hi Michael,
two questions:
Can you elaborate on why you think there's no backwards compatibility issues?
there is no point in using this resource programmatically, as it only contains enumerations available in the system for given version and some other metadata, i.e it used by developers during the coding and it's not real system resource.
In your proposal, are you leaving /api/capabilites in place as it is now?
no, please see new modelling below.
If not how to you enumerate the different versions?
since our resource id is opaque by definition - it doesn't have to be UUID, the id for version_capabilities resource can be the version itself, i.e 3.0 / 3.1 / etc. (worst case if someone likes UUID more we can convert version str. to UUID)
Regards, Geert
On 05/24/2012 09:53 AM, Michael Pasternak wrote:
the motivation: ===============
1. current design is not restfull 2. is not consistent with the rest of api impl.
impacts: ========
as this resource not used programmatically, we do not expect any backward compatibility issues
planned change is: =================
from:
http://localhost:8080/api/capabilities
<capabilities> <version major="3" minor="1"> ... <version/> <version major="3" minor="0"> ... <version/> </capabilities>
to:
http://localhost:8080/api/capabilities/x.y
<capabilities id="x.y"> <version major="x" minor="y"> ... </capabilities>
or
<capabilities id="x.y" version="x.y"> ... </capabilities>
or
http://localhost:8080/api/capabilities/UUID <capabilities id="UUID" version="x.y"> ... </capabilities>
-- Michael Pasternak RedHat, ENG-Virtualization R&D
On 05/29/2012 12:12 PM, Michael Pasternak wrote:
there is no point in using this resource programmatically, as it only contains enumerations available in the system for given version and some other metadata,
i.e it used by developers during the coding and it's not real system resource.
I'm not convinced that that is true. For example, applications can use the "power_managers" and "cpus" elements to prepopulate lists in a user interface for example.
In your proposal, are you leaving /api/capabilites in place as it is now?
no, please see new modelling below.
If not how to you enumerate the different versions?
since our resource id is opaque by definition - it doesn't have to be UUID, the id for version_capabilities resource can be the version itself, i.e 3.0 / 3.1 / etc.
(worst case if someone likes UUID more we can convert version str. to UUID)
How do you get a list of which IDs / versions are available? Regards, Geert
On 05/29/2012 04:14 PM, Geert Jansen wrote:
On 05/29/2012 12:12 PM, Michael Pasternak wrote:
there is no point in using this resource programmatically, as it only contains enumerations available in the system for given version and some other metadata,
i.e it used by developers during the coding and it's not real system resource.
I'm not convinced that that is true. For example, applications can use the "power_managers" and "cpus" elements to prepopulate lists in a user interface for example.
this is good example indeed, then what about leaving /capabilities as is [1] only adding single resource retrieval capability [2] to comply with collection/resource pattern? [1] <capabilities> <version major="3" minor="1"> ... </version> <version major="3" minor="1"> ... </version> ... </capabilities> [2] /api/capabilities/UUID <version major="3" minor="1" id=UUID> ... </version>
In your proposal, are you leaving /api/capabilites in place as it is now?
no, please see new modelling below.
If not how to you enumerate the different versions?
since our resource id is opaque by definition - it doesn't have to be UUID, the id for version_capabilities resource can be the version itself, i.e 3.0 / 3.1 / etc.
(worst case if someone likes UUID more we can convert version str. to UUID)
How do you get a list of which IDs / versions are available?
by listing all <version>s as today only adding id/href to it, /api/capabilities <capabilities> <version major="3" minor="1" id=xxx href=/api/capabilities/xxx> ... </version> <version major="3" minor="1" id=yyy href=/api/capabilities/yyy> ... </version> ... </capabilities> i.e same as for any resource in api.
Regards, Geert
-- Michael Pasternak RedHat, ENG-Virtualization R&D
On 05/29/2012 03:44 PM, Michael Pasternak wrote:
On 05/29/2012 04:14 PM, Geert Jansen wrote:
On 05/29/2012 12:12 PM, Michael Pasternak wrote:
there is no point in using this resource programmatically, as it only contains enumerations available in the system for given version and some other metadata,
i.e it used by developers during the coding and it's not real system resource.
I'm not convinced that that is true. For example, applications can use the "power_managers" and "cpus" elements to prepopulate lists in a user interface for example.
this is good example indeed, then what about leaving /capabilities as is [1] only adding single resource retrieval capability [2] to comply with collection/resource pattern?
[1]
<capabilities> <version major="3" minor="1"> ... </version> <version major="3" minor="1"> ... </version> ... </capabilities>
[2]
/api/capabilities/UUID
<version major="3" minor="1" id=UUID> ... </version>
It would work from a compatibility point of view. However - to be honest - i would leave it as it is now. You also have non-version specific capabilities there, that do not fit any model. In my view there is no way to get to a clean design here. The way i look at /api/capabilities is that is is a single global singleton resource. It isn't a collection, and neither a resource in a collection. Regards, Geert
On 05/29/2012 06:26 PM, Geert Jansen wrote:
On 05/29/2012 03:44 PM, Michael Pasternak wrote:
On 05/29/2012 04:14 PM, Geert Jansen wrote:
On 05/29/2012 12:12 PM, Michael Pasternak wrote:
there is no point in using this resource programmatically, as it only contains enumerations available in the system for given version and some other metadata,
i.e it used by developers during the coding and it's not real system resource.
I'm not convinced that that is true. For example, applications can use the "power_managers" and "cpus" elements to prepopulate lists in a user interface for example.
this is good example indeed, then what about leaving /capabilities as is [1] only adding single resource retrieval capability [2] to comply with collection/resource pattern?
[1]
<capabilities> <version major="3" minor="1"> ... </version> <version major="3" minor="1"> ... </version> ... </capabilities>
[2]
/api/capabilities/UUID
<version major="3" minor="1" id=UUID> ... </version>
It would work from a compatibility point of view. However - to be honest - i would leave it as it is now. You also have non-version specific capabilities there, that do not fit any model. In my view there is no way to get to a clean design here.
The way i look at /api/capabilities is that is is a single global singleton resource. It isn't a collection, and neither a resource in a collection.
it should have be collection of version_capabilities cause otherwise it not RESTful resource and inconsistent with other resources in api, as about /currently/ non-version specific capabilities: <permits> should be version specific as in new version will be added new permits and same for the <scheduling_policies>, can you remind me what was the reasons for making them such.
Regards, Geert
-- Michael Pasternak RedHat, ENG-Virtualization R&D
On 05/30/2012 08:45 AM, Michael Pasternak wrote:
as about/currently/ non-version specific capabilities:<permits> should be version specific as in new version will be added new permits and same for the<scheduling_policies>, can you remind me what was the reasons for making them such.
I don't know, you should ask Mark or Eoghan... Regards, Geert
participants (3)
-
Eoghan Glynn -
Geert Jansen -
Michael Pasternak