Hi, Le 21/11/2016 à 10:49, Matthieu Huin a écrit : > Thanks for bringing that up, I wanted to talk about that as well ! > Comments in line. > > ----- Original Message ----- >> From: "Tristan Cacqueray" <[email protected]> >> To: [email protected] >> Sent: Monday, November 21, 2016 3:29:54 AM >> Subject: [Softwarefactory-dev] Managesf API v2 >> >> Hello Folks, >> >> with the resources management in place, it's a good time to think about >> the API V2 of managesf. Here is a review of the current controllers and >> some proposition to improve them. >> >> # ProjectController and GroupController >> It seems like we need to drop those legacy controller since the >> resources controller cover those features. However we will lose an easy >> way to create project, where it used to be a one liner call to >> sfmanager, it now involves creating quite a complex yaml description and >> going through the ci/cd workflow of the config repo. >> >> It seems like we could keep those controllers as a simple interface to >> create and delete resources for test purpose. But we could also do that >> entirely from the client side, e.g. provides a simple CLI method to >> create resources and submit the change to the resources controller. >> >> I'll be in favor of the later so that we keep the API simple. Though it >> may certainly be a problem for the GUI based work-flow. > > Same for membership > > Agreed, there should be only one way to do things, therefore only one way to > manage projects. > What we can do to simplify things for the end user is to implement something > similar to the "tests" > endpoint: calling this specific endpoint with the CLI will generate a review > on the config repo creating the project. > It would also take care of assigning uids where needed as it might be > confusing. > >> # LocalUserController >> Change from /user to /local_user endpoint for clarity. >> >> # LocalUserBindController >> Change from /bind to /local_user/bind for simplicity > > Actually these two features should be moved to cauth where it makes more > sense. > >> # ServicesUsersController >> Change from /services_users to /user for clarity. I personally find it >> difficult to remember the difference between user, services_users and >> the actual service_user. Since services_users are actually users, let's >> use the correct path: /user. >> >> We also need to unify the interface parameters, it currently uses >> "full_name" for post and it returns "fullname" in get... Let's define an >> user object with a single set of key names, e.g.: email, username, fullname. > > Agreed, it's a bit silly ... > >> # ConfigController >> IIUC, this is just to tell if a user can create projects... I propose we >> drop that controller, and start designing a dashboard controller instead >> as suggested here: https://softwarefactory-project.io/storyboard/#!/story/2 >> >> The idea would be to have a controller that the dashboard would call to >> retrieve the informations, such as which project are relevant to a user. > > This should leverage the policy engine. I am thinking about making calls to > "authorize(rule, context, target)" available from the REST API. Otherwise we > can go the lazy way and display all possible actions, but handle correctly > "Unauthorized" type errors. > >> # TestsController and PagesController >> Likewise the Project and Group controllers, shouldn't this one be >> integrated in the resources management? >> > > Pages probably, Tests, no: it was just a facility to create template tests > and zuul config > for people not super at ease with the whole workflow. It's barely used and > documented which is > a pity, so we should probably just drop it. > >> That's it for my thoughts, I'd like to get your feedback and start >> creating the stories to implement those changes for the new /managesf/v2 >> root controller. >> >> Yours, >> -Tristan > > A few other things: > > - We should also think about error handling. Errors should be returned as > JSON content with a clear description. > - Other possible future endpoints should mimic the workflow; the objective > would be someday to completely hide the services in favor of a fully unified > GUI. > * review (list/filter, vote, etc) > * jobs (already discussed) > * issues (list/filter, create, update, delete) > * nodes (list, hold, delete) > * paste (send paste, return pastie url) > * etherpad (?) > - possible plugin arch overhaul. Instead of the rather complex current > approach of role-based plugin classes, have classes implement all possible > calls (for example the gerrit plugin would have an issue manager that would > just return a NotAvailableAction Exception at calls). > > I'm going to read that in order to fish for good ideas and practices: > https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf >
I'm thinking also to the automatic REST API doc generation from the code (docstring or other method). It is too difficult to maintain such a doc manually. >> >> _______________________________________________ >> Softwarefactory-dev mailing list >> [email protected] >> https://www.redhat.com/mailman/listinfo/softwarefactory-dev >> > > _______________________________________________ > Softwarefactory-dev mailing list > [email protected] > https://www.redhat.com/mailman/listinfo/softwarefactory-dev >
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Softwarefactory-dev mailing list [email protected] https://www.redhat.com/mailman/listinfo/softwarefactory-dev
