On Thu, 2010-04-08 at 12:06 +0200, Geert Jansen wrote:
On 04/07/2010 07:33 PM, Mark McLoughlin wrote:
> Hi,
>
> I've made a first attempt at documenting the REST API here:
>
>
https://fedorahosted.org/rhevm-api/wiki/ApiReference
>
https://fedorahosted.org/rhevm-api/wiki/VirtualMachinesCollection
>
> Basically, I just wanted to get a feel for how sane the semantics sound
> when described in prose. It seems like a fine start to me?
>
> Geert will notice that I borrowed liberally from his API reference
> style :-)
Cool :)
I would like both APIs to follow an identical schema as this way my
users have an easy way of migrating to the "official" API once it is
released as part of the product. Some current differences:
- Right now you're doing a minimal mapping of the attributes, while i
chose to make everything available. Any reason for that?
Plan is to get the basic principles of the API design fleshed out, then
quickly extend it's coverage
- I'm using names for linked objects (e.g. host, cluster) while
you
use GUIDs. But as per the discussion about immutable URLs, i will update
this so that i uses GUIDs as well.
I'm starting to lean towards using URIs rather than GUIDs
If you look at e.g.
<vm href="http://{host}/vms/{guid}">
<id>{guid}</id>
<name>foo</name>
</vm>
then the URI serves as the true global identifier for the resource, the
name serves as a human-readable identifier and the guid just seems like
bloat
I dunno, I'm struggling to justify its purpose when we have URIs
- (Potential bike shed painting alert).. You seem to be using
mixedCase for the attributes while i'm using lowercase. It a quick
consensus likely? Is there a prevailing convention in other REST APIs?
Good point ...
Your API and deltacloud both use lower_case, whereas bburke's examples
use lower-case
I deem the consensus to be lower_case. Case closed! :-)
Cheers,
Mark.