Prachi did an excellent FS document for this, and I added the high level goals 
section
To her FS link at wiki:

https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+API+refactoring

Lots of implementation details are covered in the FS. We'll update it along the 
way. 
Thanks,
-Fang

-----Original Message-----
From: Fang Wang [mailto:fang.w...@citrix.com] 
Sent: Wednesday, December 19, 2012 9:46 PM
To: cloudstack-dev@incubator.apache.org
Subject: [REVIEW/PROPOSAL] API refactoring story: goal and notes

Hi all,
After answering questions about why/what we are doing to API refactoring, I'll 
add this to the FS document.
Probably lots of people are not clear what is our motivation and what we want 
to achieve here. 
(Will add this to the wiki page. )

The goal of the API refactoring
To make the system more modular and dynamic, API refactoring is part of the 4.1 
new architecture efforts. 
Another goal is to allow developers and partners to quickly add plugins and new 
service modules and access control, making cloudstack more adaptive.
I am new on this as well In the beginning, I do not know too much about it. Now 
after working on API refactoring, I got a better understanding of the existing 
problems and our solutions. The solution is not the final perfect solution, for 
sure, feedback and suggestion is always welcome to make it a much better and 
adaptive product. 

Current problem: 
1.      Security and access check is lying around in different layers. For 
example, in apiSevlet we check the web access username/password credentials, 
apiServer checks the command existence, and several other checks, then the DB 
access check mainly is done at the service layer. So it is hard for developers 
and system admin to follow all the access and validations, to make sure all the 
checks are done correctly. To do it, developers need to be familiar with the 
various parts of the CS code. 

2.      Static: Majority of the DB access check and security validation is 
tightly coupled with the lower layer service class. This not only made the code 
hard to follow, also inherently made the policy static. This makes it 
impossible for system admin to apply a different security policy adaptively. If 
one wants to adopt a different policy, not only he needs to understand code 
scattered around, he also needs to rebuild the CS after any changes.  Any 
security role modification is not dynamic.

3.      Performance implication: Access check done at the lower service layer 
makes the error code path long. 

4.      Docs generated, CLI and APIs are loosely coupled.  

5.      Over the wire(OTW) entity is not well defined. For example, to 
listVMsCmd, it involves multiple DB access, with the large amount of data 
showing NICs, Vols, Secondary storage etc, the command can take quite a while. 

6.      Admin and user have basically the same end-point access. 

       The goal of the API refactoring is aiming to tackle these problems: 

1.      We would pull security checks, DB access checks, any related checks up 
from service layer/orchestration engine to the API layer as much as possible. 
This makes the necessary checking done more centralized and easy to follow. 
Conceptually the cloud orchestration engine layer handles the orchestration, 
the security check and the access check should have done before reaching this 
layer. This has performance benefits, since checks are done earlier instead of 
reaching deep in the code path; this also has the benefits of a clear 
architecture. The API layer does the necessary access check and role based 
authentication, makes it easier and dynamic for future policy change. New 
policy can be added easily and dynamically as a plugin to the system. 

2.      The ACL and security checks also are written as adapter plugins, hence 
make them dynamic. Users and developers and easily adapt new policy if needed. 
This made the code more modular and more adaptive.

3.      Help improves performance: Instead of finding access error layer into 
the service layer, by doing 1, we would do possible checks early in the code 
path, which helps stop the wrong access earlier in the code path. 

4.      API layer is more tightly coupled with Doc generation, and CLI. Related 
commands are grouped together, and the new @Doc annotation will help show the 
related commands in document. 

5.      We define new view objects as response objects, avoiding big DB joins 
at run time. 

6.      Separate the admin and user APIs. This is for developers to understand 
the code, which should be accessible by users, which should only be handled by 
Admin.  Hence developers will have better grasp of the role and pay attention 
to the new code added. It also helps the document generated. 

       Notes:
1.      For end users, the new APIs after refactoring looks pretty much the 
same. One big change is the ID, we will always use UUID in the over the wire 
APIs. The UUID can be created by Cloudstack, or can be provided by users (we 
call it Xid - external ID). Every UUID should be unique in the cloudstack 
system.

2.      The API layer provides a translation from the UUID to the internal 
DB_ID to the DB entity, but this translation is done internally. Outside users 
will never see DB_ID. Before the response is sending back by CS,  API layer 
replaces the internal DB_ID with the UUID. 

3.      In original FS document, the annotation of entityType in @Parameter 
points to a resource class, this is replaced by a response class. So entityType 
points to a response object, and the response class has a one-to-one mapping 
from the response to the physical entity itself. This translation work is done 
by the API layer and the entityManagerImpl. 

4.      The packages for the new API commands are all moved from the current 
com.cloud.api.commands to new location: 
org.apache.cloudstack.api.commands.user.[group name]
org.apache.cloudstack.api.commands.admin.[group_name]

The responses are also moved to new location at 
org.apache.cloudstack.api.response

More implementation details can refer to the FS document. We will also update 
the document along the way. The code is branch from master at api_refactoring.  
Since the change is not minimum, we would like the community to know and give 
feedback.

Thanks,
-Fang

 

Reply via email to