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

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 <vincent(a)massol.net>et>: > > > > > > 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 spaces as > I mentioned in the JIRA issue ( > http://jira.xwiki.org/browse/XWIKI-12206?focusedCommentId=87137&page=co… > ) >> >> 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 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, 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 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 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 > 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