10:25 a.m.
> The new design of logical network 'usages' collection came out a bit
> problematic or shall i say annoying.
> The idea is to send the entire collection elements every time a user
> wants to update a single usage otherwise the missing elements will be
> automatically removed from the collection.
>
> Example:
> having <usages><usage>VM</usage><usages>
> 1. in order to add 'display' usage to the collection i must send
'vm'
> as well.
> 2. to remove an element from the collection, i must send the entire
> collection without the desired element
> (note: in this case it is only one extra element for every update but
> in other cases it could be much more)
Yep, this seems to conflict with the general idiom around the
interpretation of missing properties in a PUT representation -
i.e. any properties omitted from the representation are ignored
and not changed.
**I'm going to explain the current modelling; this does not mean I
object to other modellings**
In the current modelling, usages are a non-trivial collection within a
Network, but they are not business entities, and thus do not have their
own 'context' (i.e, there's no: .../networks/{network:id}/usages).
This is not new to our API; VM Custom Properties behave in the same way.
If user doesn't pass custom-properties when updating a VM, they are
unchanged. But if he passes <custom_properties> element, then its contents
*replace* the previous context. This means effectively that if an existing
custom property isn't there - it will be deleted.
I understood from Avi (although I don't think you mentioned it in this
mail), that there's a bug, that if the user doesn't pass <usages> at all -
they will all be deleted. This is off course a bug, and it will be fixed.
But if user passes empty <usages> then yes, they all will be deleted.
> The solution should be:
>
<usages><vm>true</vm><display>false</display></usages>
> That way we can send a single usage having different boolean text
> without including the entire collection elements.
I wonder would a POST/DELETE idiom be more natural, if the individual
usages would be pressed into service as a psuedo-OID, e.g:
POST .../networks/network_id/usages HTTP/1.1
<usage id="VM"/>
201 Created
Location: .../networks/network_id/usages/VM
<usage id="VM" href=".../networks/network_id/usages/VM"/>
--
GET .../networks/network_id/usages HTTP/1.1
200 OK
Location: .../networks/network_id/usages/VM
<usages>
<usage id="VM" href=".../networks/network_id/usages/VM"/>
</usages>
--
POST .../networks/network_id/usages HTTP/1.1
<usage id="display"/>
201 Created
Location: .../networks/network_id/usages/display
<usage id="display"
href=".../networks/network_id/usages/display"/>
--
GET .../networks/network_id/usages HTTP/1.1
200 OK
<usages>
<usage id="VM" href=".../networks/network_id/usages/VM"/>
<usage id="display"
href=".../networks/network_id/usages/display"/>
<usages>
--
DELETE .../networks/network_id/usages/VM
204 No Content
--
GET .../networks/network_id/usages HTTP/1.1
200 OK
<usages>
<usage id="display"
href=".../networks/network_id/usages/display"/>
<usages>
So from each usage would appear like a first class resource from the
perspective of the creation/deletion idiom. If the client providing
the ID is considered inconsistent, this could be a "name" child
element instead, e.g.:
POST .../networks/network_id/usages HTTP/1.1
<usage>
<name>display</name>
</usage>
201 Created
Location: .../networks/network_id/usages/display
<usage id="display"
href=".../networks/network_id/usages/display">
<name>display</name>
</usage>
We'd need to develop an infrastructure for generating on-the-fly IDs for internal,
non-entity, collections (based on a specified field) - and then correctly following
links that contain these IDs. I like it, but it won't be trivial, so the question
is - is now the time to do it?
Ori.
Cheers,
Eoghan