Thomas actually convinced me that 2) is better. Why: how to access a space called "pages"?
It would be: /xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/ But this url has an other meaning: list all pages of the space Europe.France.Paris I have proposed to escape the space name for this kind of use-case, like this: /xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/~pages/ But this escaping using "~" is not very RESTful (it would be a custom, xwiki-specific, standard). Meanwhile the solution 2 does not have this drawback: /xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/ is very clear. We have nothing to escape. Thanks, 2015-07-06 17:43 GMT+02:00 Guillaume "Louis-Marie" Delhumeau < [email protected]>: > 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 > -- 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
