Re: [xwiki-devs] Fwd: [Proposal] Having dots as spaces separator in the REST api to handle nested spaces

For the record, what we use in our REST api is JAX-RS, a Java API to

REST urls. We do not use Restlet directly.

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

handle it?".

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 <jean.simard(a)xwiki.com>om>: > 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] > >

> [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 > > <thomas.mortagne(a)xwiki.com> 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 > >> <gdelhumeau(a)xwiki.com> wrote: > >>> I've made some experiments with Restlet. It seems there is no

> >>> 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

> that > >>> we can manually converts to "A.B.C" in our REST components. > >>> > >>> A working proof of concept of this (committed on a branch): > >>> >

> >>> > >>> 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"

> >>> 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 < > >>> gdelhumeau(a)xwiki.com&gt;gt;: > >>> > >>>> I am currently trying to implement the multiple spaces proposal to > see if > >>>> it is doable. > >>>> > >>>> 2015-07-03 11:52 GMT+02:00 vincent(a)massol.net &lt;vincent(a)massol.net : > >>>> > >>>>> > >>>>> > >>>>> > >>>>> > >>>>> > >>>>> On 3 Jul 2015 at 11:48:24, vincent(a)massol.net (vincent(a)massol.net > (mailto: > >>>>> vincent(a)massol.net)) wrote: > >>>>> > >>>>>> Just for the record, I’m -1 for the dotted solution just for

> as > >>>>> I mentioned in the JIRA issue ( > >>>>> >

> >>>>> ) > >>>>>> > >>>>>> 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 ( > fabio.mancinelli(a)xwiki.com > >>>>> (mailto:fabio.mancinelli@xwiki.com)) 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

> >>>>>>> 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

> >>>>> than > >>>>>>>> "spaces" and deprecate "spaces" or to introduce versioning

> >>>>> 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

> >>>>> So the > >>>>>>>> URL would be: > >>>>>>>> > >>>>>>>> > >>>>> >

> >>>>>>>> > >>>>>>>> > >>>>>>>> + is 100% backwards compatible > >>>>>>>> ++ old apps will only be able to access the first level, as

> >>>>> 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

> >>>>> 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

> >>>>> through NS > >>>>>>>> > >>>>>>>> +1 for dots, i.e. > >>>>>>>>

> >>>>>>>> > >>>>>>>> - 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, vincent(a)massol.net > >>>>>>>> wrote: > >>>>>>>> > >>>>>>>>> I think we should decide what we want independently of the

> >>>>> 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

> >>>>> 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 ( > >>>>>>>>> gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) 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

> >>>>> the case > >>>>>>>>> of > >>>>>>>>>> nested spaces. Example: > >>>>>>>>>> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris > >>>>>>>>>> > >>>>>>>>>> For spaces containing dots in their name, we simply escape

> >>>>> with \ > >>>>>>>>>> (%5C). > >>>>>>>>>> > >>>>>>>>>> It has the drawback to not have a similar URL than the

> >>>>> action, > >>>>>>>>> ie: > >>>>>>>>>> /xwiki/bin/view/Europe/France/Paris/WebHome - for view action > >>>>>>>>>>

> >>>>> - for > >>>>>>>>> REST > >>>>>>>>>> action > >>>>>>>>>> > >>>>>>>>>> But it does not seem possible to handle "/" in path

> >>>>> with > >>>>>>>>> Restlet. > >>>>>>>>>> ie: > >>>>>>>>>>

> >>>>>>>>>> is not supported by Restlet. > >>>>>>>>>> > >>>>>>>>>> After a talk with some Restlet committers, they confirm me

> >>>>> 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

> >>>>> free to > >>>>>>>>>> talk about this. > >>>>>>>>>> > >>>>>>>>>> Thanks, > >>>>>>>>>> Guillaume > >>>>>>>>>> > >>>>> > >>>>> _______________________________________________ > >>>>> devs mailing list > >>>>> devs(a)xwiki.org > >>>>> http://lists.xwiki.org/mailman/listinfo/devs > >>>>> > >>>> > >>>> > >>>> > >>>> -- > >>>> Guillaume Delhumeau (gdelhumeau(a)xwiki.com) > >>>> Research & Development Engineer at XWiki SAS > >>>> Committer on the XWiki.org project > >>>> > >>> > >>> > >>> > >>> -- > >>> Guillaume Delhumeau (gdelhumeau(a)xwiki.com) > >>> Research & Development Engineer at XWiki SAS > >>> Committer on the XWiki.org project > >>> _______________________________________________ > >>> devs mailing list > >>> devs(a)xwiki.org > >>> http://lists.xwiki.org/mailman/listinfo/devs > >> > >> > >> > >> -- > >> Thomas Mortagne > > > > > > > > -- > Jean Simard > jean.simard(a)xwiki.com > Research engineer at XWiki SAS > http://www.xwiki.com > Committer on the XWiki.org project > http://www.xwiki.org > _______________________________________________ > devs mailing list > devs(a)xwiki.org > http://lists.xwiki.org/mailman/listinfo/devs > -- Guillaume Delhumeau (gdelhumeau(a)xwiki.com) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs