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)

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/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> > >

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 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