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

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