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!



1. Background

The vdsm APIs that govern host networking configuration
need to be modeled in the REST API.

2. APIs implemented to REST


3. 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:


     - 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.

2). REST part:
     - Model the current network APIs in REST.

4. 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#
#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.


#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"


5. 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.
   PUT /api/networks/$network
   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 mailing list

Reply via email to