[Engine-devel] Logical network Usages collection problematic approach

[Eoghan Glynn]

> 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