Thanks for explanation, How does CS handle ID->UUID translation in response object?
Anthony > -----Original Message----- > From: Min Chen [mailto:min.c...@citrix.com] > Sent: Wednesday, December 19, 2012 10:13 PM > To: cloudstack-dev@incubator.apache.org > Subject: Re: [REVIEW/PROPOSAL/DISCUSS] API refactoring story: goal and > notes > > Here Fang is talking about UUID translation to DB_ID in constructing > our > Command class (ApiDispatcher.setupParameters), not in generating > response > object, so it will not impact list api performance. > > Thanks > -min > > On 12/19/12 10:07 PM, "Anthony Xu" <xuefei...@citrix.com> wrote: > > >>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 > >> > >>
