3 Jul
2015
3 Jul
'15
11:52 a.m.
On 3 Jul 2015 at 11:48:24, vincent(a)massol.net
(vincent@massol.net(mailto:vincent@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@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
> >> >