9:28 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.
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>
Cheers,
Eoghan
10:25 a.m.
New subject: [Engine-devel] Logical network Usages collection problematic approach
> 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
5:09 a.m.
New subject: [Engine-devel] Logical network Usages collection problematic approach
>> 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).
A-ha, I see.
I was thrown by the overloading on the term "collection", which
I would have understood as a set of resources that may be addressed
as a group.
Whereas in fact we're more talking about an aspect of the Network
representation that happens to include boolean sub-elements, right?
In which case, making this explicit via your suggestion:
<usages><vm>true</vm><display>false</display></usages>
would seem reasonable on the face of it.
However there's an implementation wrinkle in the type-mapper
framework ...
I'd understand the PUT below as meaning:
"set the VM usage to true, and leave other usages as they are".
GET .../networks/{network:id} HTTP/1.1
200 OK
<network id="{network:id}">
...
<usages><display>true</display></usages>
</network>
--
PUT .../networks/{network:id} HTTP/1.1
<network id="{network:id}">
<usages><vm>true</vm></usages>
</network>
200 OK
<network id="{network:id}">
...
<usages>
<vm>true</vm>
<display>true</display>
</usages>
</network>
as things currently stand, the type mapper called prior to the
UpdateNetwork action being initiated doesn't have access to the
*existing* network entity, so it has no way of setting the is_display
flag on the mapped entity to match the pre-existing setting.
I guess you could work around this by forcing a network lookup *prior*
to the update, so that the pre-existing display setting is available,
and then pass this entity as a template into the type mapping.
>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:
>[snip]
We'd need to develop an infrastructure for generating on-the-fly IDs
for internal,
non-entity, collections (based on a specified field)
Well, the idea was to avoid the need for generating on-the-fly OIDs,
by reusing the display "name" as the OID. But yes, it would still
involve some deviation from the established collection/sub-resource
implementation patterns.
Cheers,
Eoghan
4385
days inactive
4386
days old
2 comments
2 participants
participants (2)
-
Eoghan Glynn -
Ori Liel