>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.
I thought ID->UUID translation in API layer is a workaround, since it might cause list API performance issue. Any plan to fix it completely in backend? Anthony > -----Original Message----- > From: Fang Wang [mailto:fang.w...@citrix.com] > Sent: Wednesday, December 19, 2012 10:02 PM > To: cloudstack-dev@incubator.apache.org > Subject: RE: [REVIEW/PROPOSAL/DISCUSS] API refactoring story: goal and > notes > > 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+r > efactoring > > 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 > >
