Note: I am personally for 1). 2015-07-06 17:38 GMT+02:00 Thomas Mortagne <[email protected]>:
> On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau > <[email protected]> wrote: > > Let me resume everything. > > > > It seems that jax-rs does not have a solution for handling list > parameters > > [1] (except by using a query string, or matrix parameters, which we don't > > want). But, thanks to some hacks (example there: > > > https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c > ) > > we can manage to do it. We might find better solution afterwards. > > > > So we have several choices: > > 1 - /xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/WebHome - > "/" > > as separator for nested spaces > > 2 - Edouard's proposition: > > > /xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome > > - with multiple "spaces/" prefix > > 3 - Vincent's proposition - > > /xwiki/rest/v2/type/page/ref/wiki:Europe.France.Paris.WebHome - the > > reference version > > > > If we want to have this in M1, options 1 and 2 are more realistic. > > I don't think doing 3 is a good idea right now and this new concept > needs to be discussed more. > > 1 looks easier to implements and write but 2 is probably more > consistent with what we have today (plus it adds the feature of > listing the nested spaces of some space) so I'm more for 2. > > > > > [1] > > > http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td563656.html > > > > Thanks, > > Guillaume > > > > 2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>: > > > >> On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau > >> <[email protected]> wrote: > >> > For the record, what we use in our REST api is JAX-RS, a Java API to > >> handle > >> > REST urls. We do not use Restlet directly. > >> > >> s/We do not/We are not supposed to/ ;) > >> > >> > > >> > There are several implementations of this API: Jersey (by Oracle), > Apaxe > >> > CXF, etc... From what I've understood, Reslet is not a jax-rs > >> > implementation, but it provides one. This is why I had some issues > while > >> > browsing the Restlet documentation, assuming it was only about JAX-RS. > >> > > >> > So actually the question is not "can Restlet handle this?" but "can > >> JAX-RS > >> > handle it?". > >> > >> Yep. > >> > >> > If the answer is no, changing or upgrading our framework will > >> > not solve anything, unless we decide to stop using JAX-RS too. > >> > > >> > > >> > > >> > 2015-07-06 14:11 GMT+02:00 Jean SIMARD <[email protected]>: > >> > > >> >> Indeed, we may check. However, in the documentation of restlet, > there > >> >> is still sentences like "Note that this implementation is not final > >> >> yet." (which seems here forever) and "This extension is the result > of a > >> >> (german) master thesis." which doesn't mean the work is bad but which > >> >> usually mean no maintenance after the thesis [1]. It looks like > restlet > >> >> is a bit risky. > >> >> > >> >> The implementation seems not very alive on the Github account [2]. > >> >> > >> >> [1] > >> >> > >> >> > >> > http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/jaxrs > >> >> [2] https://github.com/restlet/restlet-framework-java > >> >> > >> >> PS: Thanks to Fabio for some information about that > >> >> > >> >> On 06/07/2015 13:58, Thomas Mortagne wrote: > >> >> > On Mon, Jul 6, 2015 at 1:57 PM, Thomas Mortagne > >> >> > <[email protected]> wrote: > >> >> >> Did you check in more recent versions of Restlet ? Ours is > tarting to > >> >> >> be pretty old. > >> >> > > >> >> > (2.0.14 vs 2.3.3) > >> >> > > >> >> >> On Mon, Jul 6, 2015 at 1:26 PM, Guillaume "Louis-Marie" Delhumeau > >> >> >> <[email protected]> wrote: > >> >> >>> I've made some experiments with Restlet. It seems there is no > >> solution > >> >> >>> out-of-the-box to handle multiple level of nesting in the URL > path. > >> >> But we > >> >> >>> can actually cheat. > >> >> >>> > >> >> >>> We can define a path with this syntax: > >> >> >>> @Path("/wikis/{wikiName}/spaces/{spaceName: > .+}/pages/{pageName}") > >> >> >>> > >> >> >>> Here, {spaceName: .+} means that any character could be present, > >> >> including > >> >> >>> a slash. > >> >> >>> > >> >> >>> So we can actually retrieve the spaces list as a string, like > >> "A/B/C", > >> >> that > >> >> >>> we can manually converts to "A.B.C" in our REST components. > >> >> >>> > >> >> >>> A working proof of concept of this (committed on a branch): > >> >> >>> > >> >> > >> > https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c > >> >> >>> > >> >> >>> So we can use /xwiki/rest/wikis/xwiki/spaces/A/B/C as a valid > URL. > >> >> >>> > >> >> >>> With the same trick, we can implement the multiple "spaces" > >> proposal: > >> >> >>> https://github.com/xwiki/xwiki-platform/commit/3e83b6cf44e8 > >> >> >>> it actually delegates to the component the parsing of the spaces > >> >> segments. > >> >> >>> > >> >> >>> It might not be as clean as a proper custom router, but at least > is > >> >> >>> feasible without rewriting everything. > >> >> >>> > >> >> >>> What do you think? > >> >> >>> > >> >> >>> > >> >> >>> > >> >> >>> > >> >> >>> 2015-07-06 12:02 GMT+02:00 Guillaume "Louis-Marie" Delhumeau < > >> >> >>> [email protected]>: > >> >> >>> > >> >> >>>> I am currently trying to implement the multiple spaces proposal > to > >> >> see if > >> >> >>>> it is doable. > >> >> >>>> > >> >> >>>> 2015-07-03 11:52 GMT+02:00 [email protected] < > [email protected] > >> >: > >> >> >>>> > >> >> >>>>> > >> >> >>>>> > >> >> >>>>> > >> >> >>>>> > >> >> >>>>> > >> >> >>>>> On 3 Jul 2015 at 11:48:24, [email protected] ( > [email protected] > >> >> (mailto: > >> >> >>>>> [email protected])) wrote: > >> >> >>>>> > >> >> >>>>>> Just for the record, I’m -1 for the dotted solution just for > >> spaces > >> >> as > >> >> >>>>> I mentioned in the JIRA issue ( > >> >> >>>>> > >> >> > >> > http://jira.xwiki.org/browse/XWIKI-12206?focusedCommentId=87137&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137 > >> >> >>>>> ) > >> >> >>>>>> > >> >> >>>>>> If we want to use “dots” then I much prefer that we use the > >> >> serialized > >> >> >>>>> reference as in: > >> >> >>>>>> > >> >> >>>>>> /rest/v2/type//ref/ > >> >> >>>>>> > >> >> >>>>>> Examples: > >> >> >>>>>> > >> >> >>>>>> /rest/v2/property/wiki:space1.space2.page^object.property > >> >> >>>>>> /rest/v2/object/wiki:space1.space2.page^object > >> >> >>>>>> /rest/v2/attachment/wiki:space1.space2.page@filename > >> >> >>>>>> /rest/v2/page/wiki:space1.space2.page > >> >> >>>>>> /rest/v2/space/wiki:space1.space2 > >> >> >>>>>> /rest/v2/wiki/wiki > >> >> >>>>> > >> >> >>>>> I meant the following (to be self-describing): > >> >> >>>>> > >> >> >>>>> > /rest/v2/type/property/ref/wiki:space1.space2.page^object.property > >> >> >>>>> /rest/v2/type/object/ref/wiki:space1.space2.page^object > >> >> >>>>> /rest/v2/type/attachment/ref/wiki:space1.space2.page@filename > >> >> >>>>> /rest/v2/type/page/ref/wiki:space1.space2.page > >> >> >>>>> /rest/v2/type/space/ref/wiki:space1.space2 > >> >> >>>>> /rest/v2/type/wiki/ref/wiki > >> >> >>>>> > >> >> >>>>> Thanks > >> >> >>>>> -Vincent > >> >> >>>>> > >> >> >>>>>> Note that this leads to shorter and simpler URLs. > >> >> >>>>>> > >> >> >>>>>> Thanks > >> >> >>>>>> -Vincent > >> >> >>>>>> > >> >> >>>>>> On 3 Jul 2015 at 11:20:14, Fabio Mancinelli ( > >> >> [email protected] > >> >> >>>>> (mailto:[email protected])) wrote: > >> >> >>>>>> > >> >> >>>>>>> Hi, > >> >> >>>>>>> > >> >> >>>>>>> We should check how to declare a URI Template of the form > >> >> >>>>>>> /rest/wikis/xwiki/(spaces/SPACE)+/pages/PAGE in JAX-RS... The > >> Spec > >> >> >>>>>>> allows regexs in the URI Template defintion in @Path > annotations > >> >> but > >> >> >>>>>>> this is something to be checked. I am not sure that it's that > >> >> simple. > >> >> >>>>>>> > >> >> >>>>>>> Given the previous remark, maybe the dotted solution might be > >> >> easier > >> >> >>>>> to handle. > >> >> >>>>>>> > >> >> >>>>>>> Of course API versioning is a very good thing to have. > >> >> >>>>>>> > >> >> >>>>>>> Thanks, > >> >> >>>>>>> Fabio > >> >> >>>>>>> > >> >> >>>>>>> > >> >> >>>>>>> > >> >> >>>>>>> > >> >> >>>>>>> On Fri, Jul 3, 2015 at 12:55 AM, Eduard Moraru wrote: > >> >> >>>>>>>> Hi, > >> >> >>>>>>>> > >> >> >>>>>>>> Initially, I wanted to go with the dots, however the > backwards > >> >> >>>>>>>> compatibility problem would force us to either use a > different > >> key > >> >> >>>>> than > >> >> >>>>>>>> "spaces" and deprecate "spaces" or to introduce versioning > >> (i.e. > >> >> >>>>> path > >> >> >>>>>>>> prefix like /rest/v1/wikis...), as Vincent said. > >> >> >>>>>>>> > >> >> >>>>>>>> However, the multiple "spaces" (I think this is what you > meant, > >> >> >>>>> Vincent) > >> >> >>>>>>>> alternative has more (I`d say only) advantages than > >> disadvantages. > >> >> >>>>> So the > >> >> >>>>>>>> URL would be: > >> >> >>>>>>>> > >> >> >>>>>>>> > >> >> >>>>> > >> >> > >> > /xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome > >> >> >>>>>>>> > >> >> >>>>>>>> > >> >> >>>>>>>> + is 100% backwards compatible > >> >> >>>>>>>> ++ old apps will only be able to access the first level, as > >> they > >> >> >>>>> were > >> >> >>>>>>>> designed > >> >> >>>>>>>> ++ No mixup between space name (unescaped) vs space > reference > >> >> >>>>> (escaped) > >> >> >>>>>>>> ++ As a result, no need to introduce any versioningjust yet > >> >> >>>>>>>> > >> >> >>>>>>>> + indeed is much more restful, since at each step (e.g. > France) > >> >> you > >> >> >>>>> can > >> >> >>>>>>>> have either subspaces (e.g. Paris) or pages (e.g. WebHome or > >> any > >> >> >>>>> other > >> >> >>>>>>>> terminal page) > >> >> >>>>>>>> ++ in other words, the resource hierarchy is better exposed > >> >> >>>>>>>> > >> >> >>>>>>>> + Bonus, we stick to the good old "/" separator > >> >> >>>>>>>> > >> >> >>>>>>>> + Reflects perfectly the expansion of the model that we are > >> doing > >> >> >>>>> through NS > >> >> >>>>>>>> > >> >> >>>>>>>> +1 for dots, i.e. > >> >> >>>>>>>> > >> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris/pages/WebHome > >> >> >>>>>>>> > >> >> >>>>>>>> - longer URLs for long paths > >> >> >>>>>>>> > >> >> >>>>>>>> So I`m +1 for the "multiple spaces" option. > >> >> >>>>>>>> > >> >> >>>>>>>> Thanks, > >> >> >>>>>>>> Eduard > >> >> >>>>>>>> > >> >> >>>>>>>> On Thu, Jul 2, 2015 at 6:14 PM, [email protected] > >> >> >>>>>>>> wrote: > >> >> >>>>>>>> > >> >> >>>>>>>>> I think we should decide what we want independently of the > >> REST > >> >> >>>>> framework > >> >> >>>>>>>>> impl, to be the most restful possible. > >> >> >>>>>>>>> > >> >> >>>>>>>>> Then we check how to do it in the REST fwk we currently use > >> >> >>>>> (restlet) and > >> >> >>>>>>>>> if not possible then we should check if it’s possible with > >> some > >> >> >>>>> other REST > >> >> >>>>>>>>> fwk (jersey for example). > >> >> >>>>>>>>> > >> >> >>>>>>>>> At worse, if we don’t want to wait we will need at least to > >> >> >>>>> introduce API > >> >> >>>>>>>>> versioning so that we can change it later on easily. > >> >> >>>>>>>>> > >> >> >>>>>>>>> There’s also the suggestion I proposed with several “pages” > >> >> >>>>> elements which > >> >> >>>>>>>>> seems potentially more restful than dots to me (but leads > to > >> >> >>>>> longer urls). > >> >> >>>>>>>>> > >> >> >>>>>>>>> So IMO you should research more about what is the RESTful > >> >> approach > >> >> >>>>> to this > >> >> >>>>>>>>> before we can decide anything. > >> >> >>>>>>>>> > >> >> >>>>>>>>> Thanks > >> >> >>>>>>>>> -Vincent > >> >> >>>>>>>>> > >> >> >>>>>>>>> On 2 Jul 2015 at 15:57:53, Guillaume Louis-Marie Delhumeau > ( > >> >> >>>>>>>>> [email protected](mailto:[email protected])) wrote: > >> >> >>>>>>>>> > >> >> >>>>>>>>>> Hi. > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> This proposal is already explained in > >> >> >>>>>>>>>> http://jira.xwiki.org/browse/XWIKI-12206. I think it is > an > >> >> >>>>> important > >> >> >>>>>>>>> issue > >> >> >>>>>>>>>> to fix because it blocks > >> >> >>>>> http://jira.xwiki.org/browse/XWIKI-12198 > >> >> >>>>>>>>> (Ensure > >> >> >>>>>>>>>> annotations work on nested spaces). > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> The current REST URL for a space is: > >> >> >>>>>>>>>> /xwiki/rest/wikis/xwiki/spaces/Europe > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> and for a page: > >> >> >>>>>>>>>> /xwiki/rest/wikis/xwiki/spaces/Europe/pages/WebHome > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> The idea is to use dots as space separator in the REST > URLs > >> in > >> >> >>>>> the case > >> >> >>>>>>>>> of > >> >> >>>>>>>>>> nested spaces. Example: > >> >> >>>>>>>>>> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> For spaces containing dots in their name, we simply escape > >> them > >> >> >>>>> with \ > >> >> >>>>>>>>>> (%5C). > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> It has the drawback to not have a similar URL than the > >> standard > >> >> >>>>> action, > >> >> >>>>>>>>> ie: > >> >> >>>>>>>>>> /xwiki/bin/view/Europe/France/Paris/WebHome - for view > action > >> >> >>>>>>>>>> > >> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris/pages/WebHome > >> >> >>>>> - for > >> >> >>>>>>>>> REST > >> >> >>>>>>>>>> action > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> But it does not seem possible to handle "/" in path > >> parameters > >> >> >>>>> with > >> >> >>>>>>>>> Restlet. > >> >> >>>>>>>>>> ie: > >> >> >>>>>>>>>> > >> /xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/WebHome > >> >> >>>>>>>>>> is not supported by Restlet. > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> After a talk with some Restlet committers, they confirm me > >> that > >> >> >>>>> we have > >> >> >>>>>>>>> to > >> >> >>>>>>>>>> write our own URL router to handle this. I don't know if > it > >> >> >>>>> worth the > >> >> >>>>>>>>> pain > >> >> >>>>>>>>>> although I don't have evaluated it. > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> So I guess this proposal using dots is the best option, > but > >> I'm > >> >> >>>>> free to > >> >> >>>>>>>>>> talk about this. > >> >> >>>>>>>>>> > >> >> >>>>>>>>>> Thanks, > >> >> >>>>>>>>>> Guillaume > >> >> >>>>>>>>>> > >> >> >>>>> > >> >> >>>>> _______________________________________________ > >> >> >>>>> devs mailing list > >> >> >>>>> [email protected] > >> >> >>>>> http://lists.xwiki.org/mailman/listinfo/devs > >> >> >>>>> > >> >> >>>> > >> >> >>>> > >> >> >>>> > >> >> >>>> -- > >> >> >>>> Guillaume Delhumeau ([email protected]) > >> >> >>>> Research & Development Engineer at XWiki SAS > >> >> >>>> Committer on the XWiki.org project > >> >> >>>> > >> >> >>> > >> >> >>> > >> >> >>> > >> >> >>> -- > >> >> >>> Guillaume Delhumeau ([email protected]) > >> >> >>> Research & Development Engineer at XWiki SAS > >> >> >>> Committer on the XWiki.org project > >> >> >>> _______________________________________________ > >> >> >>> devs mailing list > >> >> >>> [email protected] > >> >> >>> http://lists.xwiki.org/mailman/listinfo/devs > >> >> >> > >> >> >> > >> >> >> > >> >> >> -- > >> >> >> Thomas Mortagne > >> >> > > >> >> > > >> >> > > >> >> > >> >> -- > >> >> Jean Simard > >> >> [email protected] > >> >> Research engineer at XWiki SAS > >> >> http://www.xwiki.com > >> >> Committer on the XWiki.org project > >> >> http://www.xwiki.org > >> >> _______________________________________________ > >> >> devs mailing list > >> >> [email protected] > >> >> http://lists.xwiki.org/mailman/listinfo/devs > >> >> > >> > > >> > > >> > > >> > -- > >> > Guillaume Delhumeau ([email protected]) > >> > Research & Development Engineer at XWiki SAS > >> > Committer on the XWiki.org project > >> > _______________________________________________ > >> > devs mailing list > >> > [email protected] > >> > http://lists.xwiki.org/mailman/listinfo/devs > >> > >> > >> > >> -- > >> Thomas Mortagne > >> _______________________________________________ > >> devs mailing list > >> [email protected] > >> http://lists.xwiki.org/mailman/listinfo/devs > >> > > > > > > > > -- > > Guillaume Delhumeau ([email protected]) > > Research & Development Engineer at XWiki SAS > > Committer on the XWiki.org project > > _______________________________________________ > > devs mailing list > > [email protected] > > http://lists.xwiki.org/mailman/listinfo/devs > > > > -- > Thomas Mortagne > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
