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

Let me resume everything. It seems that jax-rs does not have a solution for handling list

[1] (except by using a query string, or matrix parameters, which we don't want). But, thanks to some hacks (example there:

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:

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

[1]

Thanks, Guillaume 2015-07-06 16:02 GMT+02:00 Thomas Mortagne <thomas.mortagne(a)xwiki.com>om>: > On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau > <gdelhumeau(a)xwiki.com> 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),

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

> > 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 <jean.simard(a)xwiki.com>om>: > > > >> Indeed, we may check. However, in the documentation of restlet,

> >> is still sentences like "Note that this implementation is not final > >> yet." (which seems here forever) and "This extension is the result

> >> (german) master thesis." which doesn't mean the work is bad but which > >> usually mean no maintenance after the thesis [1]. It looks like

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

> >> >> 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 > solution > >> >>> out-of-the-box to handle multiple level of nesting in the URL

> >> But we > >> >>> can actually cheat. > >> >>> > >> >>> We can define a path with this syntax: > >> >>> @Path("/wikis/{wikiName}/spaces/{spaceName:

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

> >> >>> > >> >>> So we can use /xwiki/rest/wikis/xwiki/spaces/A/B/C as a valid

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

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

> >> see if > >> >>>> it is doable. > >> >>>> > >> >>>> 2015-07-03 11:52 GMT+02:00 vincent(a)massol.net <

> >: > >> >>>> > >> >>>>> > >> >>>>> > >> >>>>> > >> >>>>> > >> >>>>> > >> >>>>> On 3 Jul 2015 at 11:48:24, vincent(a)massol.net (

> >> (mailto: > >> >>>>> vincent(a)massol.net)) wrote: > >> >>>>> > >> >>>>>> Just for the record, I’m -1 for the dotted solution just for > spaces > >> 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/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 > Spec > >> >>>>>>> allows regexs in the URI Template defintion in @Path

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

> >> >>>>>>>> compatibility problem would force us to either use a

> 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

> >> >>>>> Vincent) > >> >>>>>>>> alternative has more (I`d say only) advantages than > disadvantages. > >> >>>>> So the > >> >>>>>>>> URL would be: > >> >>>>>>>> > >> >>>>>>>> > >> >>>>> > >> >

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

> >> >>>>> (escaped) > >> >>>>>>>> ++ As a result, no need to introduce any versioningjust yet > >> >>>>>>>> > >> >>>>>>>> + indeed is much more restful, since at each step (e.g.

> >> 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, vincent(a)massol.net > >> >>>>>>>> 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

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

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

> 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

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

> >> >>>>> worth the > >> >>>>>>>>> pain > >> >>>>>>>>>> although I don't have evaluated it. > >> >>>>>>>>>> > >> >>>>>>>>>> So I guess this proposal using dots is the best option,

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