<html><head><style type='text/css'>p { margin: 0; }</style></head><body><div style='font-family: Times New Roman; font-size: 12pt; color: #000000'><div style="color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;"><style></style><div style="font-family: Times New Roman; font-size: 12pt; color: #000000">Hi All,<br><br>I would like to hear opinions about a behaviour that I think is problematic in<br>REST API handling of logical networks.<br><br>-- Intro --<br>Today in the REST API we are exposing two collections for "logical<br>network" related entities.<br><br>First is a top level collection which is out of any context at the address <br>http://engine/api/networks.<br>Second is a sub-collection in the context of a cluster: <br>http://engine/api/cluster/xxx/networks<br><br>The network itself is defined per DC level, so for each DC you would have <br>at least one logical network for management, which has some properties such<br>as STP, MTU, etc..<br>The top level collection is used to create/delete such network entities.<br><br>The sub-collection in the context of a Cluster is used to attach/detach a <br>network from the DC of that cluster.<br>The network in the context of a cluster has some additional information, let's<br>say for example 'status' of the network:<br> If a network is defined on all hosts in the cluster then it's status is <br> 'Operational'.<br> If a network is not defined on some of the hosts in the cluster then it's <br> status is 'Not Operational'[1].<br><br><br>-- Problem --<br>The problem is that details which are only relevant in context of a<br>cluster, are still displayed in the root context as well (e.g: 'status').<br>
This can, in certain cases, cause unexpected behaviour.<br><br>For example, let's consider this topology:<br> Data Center A<br> |<br> |\____ Network 'red'<br> |\____ Cluster A1<br> | \______ Network 'red' attached<br> \____ Cluster A2<br> \______ Network 'red' attached<br><br>If the 'status' is the same on all the clusters that the network is attached to<br>(A1, A2) then there will be one element in the top level collection, with the<br>network details and the 'status' field representing the state (which is same<br>for all networks in the cluster contexts of the cluster).<br>If, however, the status is not the same (ie. on A1 the network is<br>'Operational' and on A2 it is 'Non Operational') then the top-level <br>collection will show two elements for the network, where all network<br>details are the same and only the 'status' field is different.<br><br>This is problematic IMHO for several reasons:<br> 1. Showing one network in certain states, and multiple copies of this<br> network in other states is not optimal, to say the least.<br> 2. In the top-level collection there is no indicator of the cluster for which<br> the network is displayed, so there is no way to differentiate between the<br> two 'red' network elements (they will have same id, name, etc.).<br> 3. There is a certain asymmetry between the remove action[2] and the <br> result in that you would expect: you either remove a network but in the<br> result you would see several elements removed.<br><br><br>-- Proposed Solutions --<br>Personally I can think of several solutions to this problem:<br> 1. Declare the top-level collection as a collection of all networks that are<br> either attached to cluster or not, and if they are indeed attached then<br> show the details for each cluster, including a link to the cluster.<br> 2. Declare the top-level collection as a collection of all networks that are<br> defined in data-centers, but they will not contain any cluster specific<br> data, and thus each entry is unique.<br><br>Solution #2 is breaking the API backwards-compatibility, since it includes<br>removing certain fields that have appeared today (namely 'status' and<br>'display') but IMO would give a better experience since the top-level<br>collection is actually used for managing networks, and not their attachment<br>to clusters which should be done in the context of each cluster.<br><br>I would like to hear what suggestions you have to solve this problem or if<br>you prefer either of the above solutions.<br><br><br>-- Footnotes --<br>[1] In 3.1 this is slightly different, but for the sake of simplicity I didn't<br> specify the new behaviour.<br>[2] Currently you can't update the network if it's attached to any cluster,<br> but perhaps in the future this would be possible.<br><br><div><span></span>Regards,<br>Mike<span></span><br></div><br></div></div><br></div></body></html>