On 06/07/2012 05:10 AM, Adam Litke wrote:
Please see my comments inline...
Hi Adam,
Thanks very much for your detailed comments! I send this out to have discussion earlier to make sure I am in the right direction. Now I am still struggling to adjust to your new infrastructure..
On Thu, Jun 07, 2012 at 04:36:48AM +0800, Lei HH Li wrote:
Hi guys,
This proposal describes how we plan to model networks in rest-api. The current code is based on the Adam's old rest-api base, and now I am working on adjusting to Adam's new basic server infrastructure and support xml format as well.
As Adam's new rest-api modules is going to upstream, I'd like to send this out to have your suggestion.
Any comments would be appreciated!
Thanks!
-- Lei
- Background
The vdsm APIs that govern host networking configuration need to be modeled in the REST API.
- APIs implemented to REST
addNetwork delNetwork editNetwork setSafeNetConfig setupNetworks
- The design and implement
1). Internal vdsm part:
These changes are completely independent of the REST API stuff.
Yes, based on the last comment from Dan that he think the motivation for the patch is not completely clear to him, and suggested send a following patch using this refactoring, so I think it would be better to write the whole stuff here. The previous patch link:
http://gerrit.ovirt.org/#/c/2663/
- Reorganize the network APIs into a Network class within API bridge.
I think you can do this one right away because it does not require much debate or discussion. It is clearly better to reorganize the code in API.py to conform to the object model that the rest of the functions use.
Yes, it is clearly. A little concern as replied above.
- Add functions like getting a list of configured networks, and getting information for specified network to API bridge. - getNetworkList - getNetworkInfo(network)
Could you write up a specification of all new APIs that you would like to add? Please document the function name and purpose, the precise format of the parameters and return value, and the semantics/behavior of the function.
Sure.
2). REST part: - Model the current network APIs in REST.
- Model network in REST
The current modelling is based on JSON only templates, will adjust to Adam's new basic server infrastructure and support xml format as well.
{ "resource": "network",
Today's templates omit the 'resource' field.
Yes, all of this are just based on the old rest infrastructure.
"id": "$network", "href": "/api/networks/$network" "vlan": "$vlan",
Please descibe the format of this field.
"bonding": "$bonding",
Please descibe the format of this field.
"nics": [ #set first = 1 #for $nic in $nics #if first == 1# #set first = 0# #else# ,#end if# "$nic", #end for ], #if 'ipaddr' in $options "ipaddr": "$options['ipaddr']", "netmask": "$options['netmask']", "gateway": "$options['gateway']", #end if #if 'bridged' in $options "bridged": "$options['bridged']",
Please descibe the format of this field.
#end if #if 'force' in $options "force": "$options['Force']",
Please descibe the format of this field.
#end if "actions": { "view": "/api/networks/$network/"
This is not an action. It is always assumed that you can send a GET request to a resource to get its representation.
"delete": "/api/networks/$network/delete"
I haven't updated the templates yet but delete will not be an action anymore. Instead, delete will be accomplished by sending a DELETE HTTP request to the resource URI directly. See my latest patches for how this is implemented.
OK. Now I am trying to adjust to your branch, but certainly it's not the latest version. I will rebase to it.
"edit": "/api/networks/$network/edit"
I wonder if 'edit' should be implemented as a PUT request on the resource URI. In order to know for sure, we should enumerate all of the things that you can change with the editNetwork command to see if there are any ambiguous scenarios.
} }
{ "networks": [ #set first = 1 #for $network in $networks #if first == 1# #set first = 0# #else# ,#end if# { "id": "$network", "href": "/api/networks/$network" }
In the latest templates, the collection fully describes all of its member resources. See the templates in my current series for examples.
Yes, I am coding like that.
#end for ], "actions": { "add": "/api/networks/add"
Add is implemented as a POST request on the collection URI. See my latest patches for how this is implemented.
"confirm": "/api/networks/confirm"
Ok.
} }
- URL
For the function setupNetworks, mark as TODO due to some technology issue and need more discussion with engine.
Since we now use multiple HTTP methods, you should add a new column to this table to indicate the method. See comments.
/api/networks/ .................Get a list of networks configured for vdsm. Would call function getNetworkList which is wrapped in index() in REST model.
GET /api/networks
/api/networks/confirm...........Mark the current network config as safe. Would expose setSafeNetConfig function.
POST /api/networks/confirm
/api/networks/add...............Add a new network. Would call addNetwork.
POST /api/networks As mentioned above, the POST goes to the collection URI.
/api/networks/$network/.........View details of the network. Would call function getNetworkInfo which is wrapped in lookup() in REST model.
GET /api/networks/$network
/api/networks/$network/edit.....Edit the network. Would expose editNetwork function.
Either: PUT /api/networks/$network or: POST /api/networks/$network/edit
Depending on the result of the editNetwork use case analysis.
/api/networks/$network/delete...Delete the network. Would expose delNetwork function.
DELETE /api/networks/$network
vdsm-devel@lists.fedorahosted.org