[xwiki-devs] Fwd: [Proposal] Having dots as spaces separator in the REST api to handle nested spaces
2 Jul
2015
2 Jul
'15
3:57 p.m.
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
--
Guillaume Delhumeau (guillaume.delhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
2 Jul
2 Jul
4:08 p.m.
Are you talking about introducing a special syntax or is the idea to
put the space reference (which is not the same as saying that space
are separated by space, reference syntax is documented and have
associated resolver/serializers) instead of the space name like in the
document table ?
On Thu, Jul 2, 2015 at 3:57 PM, Guillaume "Louis-Marie" Delhumeau
<gdelhumeau(a)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
--
Guillaume Delhumeau (guillaume.delhumeau(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
5:14 p.m.
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
--
Guillaume Delhumeau (guillaume.delhumeau(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
3 Jul
3 Jul
12:55 a.m.
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 <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
--
Guillaume Delhumeau (guillaume.delhumeau(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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
8:51 a.m.
+1 for multiple spaces
It's the simplest from retro compatibility point of view since it's
actually don't really change anything and nothing prevent us from
introducing some other scheme for REST later if e really want to.
On Fri, Jul 3, 2015 at 12:55 AM, Eduard Moraru <enygma2002(a)gmail.com> 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 <vincent(a)massol.net>
wrote:
--
Thomas Mortagne
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:
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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
--
Guillaume Delhumeau (guillaume.delhumeau(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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
11:20 a.m.
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 <enygma2002(a)gmail.com> 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 <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:
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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
--
Guillaume Delhumeau (guillaume.delhumeau(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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
11:48 a.m.
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/<entity type>/ref/<reference>
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
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
>> >
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
> >> >
6 Jul
6 Jul
12:02 p.m.
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:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
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
1:26 p.m.
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 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 "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):
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
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" 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 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;:
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>:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
On 3 Jul 2015 at 11:48:24, vincent(a)massol.net (vincent(a)massol.net(mailto:
vincent(a)massol.net)) wrote:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
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
1:41 p.m.
From what I understood (and from the link I send), you
have to do this
way, i.e. parse some slashes in the path and do the real parser in
your
implementation (but I didn't dig that much).
Keep also in mind that restlet is probably not the best implementation
of jax-rs (it's kind of a tricky implementation on top of real restlet).
It may be the right time to consider another one like Vincent already
said? Jersey, RestEasy seems to be 2 nice candidates.
On 06/07/2015 13:26, Guillaume "Louis-Marie" Delhumeau 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 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 "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):
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
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" 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 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;:
--
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
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:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
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
1:57 p.m.
Did you check in more recent versions of Restlet ? Ours is tarting to
be pretty old.
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 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 "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):
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
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" 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 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;:
--
Thomas Mortagne
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>:
--
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
On 3 Jul 2015 at 11:48:24, vincent(a)massol.net (vincent(a)massol.net(mailto:
vincent(a)massol.net)) wrote:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
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
1:58 p.m.
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:
--
Thomas Mortagne
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 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 "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):
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
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" 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 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;:
--
Thomas Mortagne 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>:
--
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
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
2:11 p.m.
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]
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
[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:
--
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
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 solution
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 "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):
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
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" 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 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;:
--
Thomas Mortagne 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
--
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
3:51 p.m.
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.
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 JAX-RS
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]
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
[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:
--
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
On Mon, Jul 6, 2015 at 1:57 PM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
But
we
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 solution
>> out-of-the-box to handle multiple level of nesting in the URL path. >> 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 "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):
>>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
>>
>> 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" 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 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;:
>>
>>> 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
>
--
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
4:02 p.m.
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), 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
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>:
--
Thomas Mortagne
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]
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
[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:
--
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 On Mon, Jul 6, 2015 at 1:57 PM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
But
we
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 solution
>> out-of-the-box to handle multiple level of nesting in the URL path. >> 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 "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):
>>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
>>
>> 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" 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 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;:
>>
>>> 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
>>
>
>
>
> --
> 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
5:11 p.m.
Let me resume everything.
It seems that jax-rs does not have a solution for handling list parameters
[1] (except by using a query string, or matrix parameters, which we don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
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:
:
> >>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>> 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
--
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
_______________________________________________
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
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), 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
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, 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]
>
>
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
> [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
solution
> >>> 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
"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):
> >>>
>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
> >>>
> >>> 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"
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 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;:
>>
>>> 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
> 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
>>>
>>
>>
>>
>> --
>> 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
5:37 p.m.
Hi,
On 6 Jul 2015 at 17:12:11, Guillaume Louis-Marie Delhumeau
(gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) wrote:
Let me resume everything.
It seems that jax-rs does not have a solution for handling list parameters
[1] (except by using a query string, or matrix parameters, which we don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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.
So for me:
Sol1 seems the best since it’s the most readable one and from what you say sol2 doesn’t
bring any implementation improvement (actually it’s more complex to implement sol2 than
sol1! https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e… vs https://github.com/xwiki/xwiki-platform/commit/3e83b6cf44e8#diff-3d532b9e95… )
Sol3 is the best IMO (the shortest but also supports all Entity Types) but it’s for
later.
Thanks
-Vincent
[1]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
Thanks,
Guillaume
[snip]
5:38 p.m.
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
Let me resume everything.
It seems that jax-rs does not have a solution for handling list parameters
[1] (except by using a query string, or matrix parameters, which we don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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.
I don't think doing 3 is a good idea right now and this new concept
needs to be discussed more.
1 looks easier to implements and write but 2 is probably more
consistent with what we have today (plus it adds the feature of
listing the nested spaces of some space) so I'm more for 2.
[1]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
Thanks,
Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <thomas.mortagne(a)xwiki.com>om>:
--
Thomas Mortagne
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume
"Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
spaces
--
Thomas Mortagne
_______________________________________________
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 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), 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
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, 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]
>
>
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
> [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
solution
> >>> 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
"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):
> >>>
>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
> >>>
> >>> 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"
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 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;:
>>>
>>>> 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
:
> >>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>> 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 (
> >>>>>
>
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
>>>>
>>>
>>>
>>>
>>> --
>>> 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
5:43 p.m.
Note: I am personally for 1).
2015-07-06 17:38 GMT+02:00 Thomas Mortagne <thomas.mortagne(a)xwiki.com>om>:
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume
"Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
--
Thomas Mortagne
_______________________________________________
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
Let me resume everything.
It seems that jax-rs does not have a solution for handling list
parameters
[1] (except by using a query string, or matrix
parameters, which we don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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.
I don't think doing 3 is a good idea right now and this new concept
needs to be discussed more.
1 looks easier to implements and write but 2 is probably more
consistent with what we have today (plus it adds the feature of
listing the nested spaces of some space) so I'm more for 2.
[1]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
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),
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
> 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,
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]
> >>
> >>
>
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
> >> [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
> solution
> >> >>> 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
> "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):
> >> >>>
> >>
>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
> >> >>>
> >> >>> 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"
> 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
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;:
> >> >>>
> >> >>>> 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
> >:
> >> >>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>> 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
--
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 > >>>>> 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
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
6:13 p.m.
Thomas actually convinced me that 2) is better.
Why: how to access a space called "pages"?
It would be:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/
But this url has an other meaning: list all pages of the space
Europe.France.Paris
I have proposed to escape the space name for this kind of use-case, like
this:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/~pages/
But this escaping using "~" is not very RESTful (it would be a custom,
xwiki-specific, standard).
Meanwhile the solution 2 does not have this drawback:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/
is very clear. We have nothing to escape.
Thanks,
2015-07-06 17:43 GMT+02:00 Guillaume "Louis-Marie" Delhumeau <
gdelhumeau(a)xwiki.com>gt;:
Note: I am personally for 1).
2015-07-06 17:38 GMT+02:00 Thomas Mortagne <thomas.mortagne(a)xwiki.com>om>:
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume
"Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
--
Thomas Mortagne
_______________________________________________
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
Let me resume everything.
It seems that jax-rs does not have a solution for handling list
parameters
[1] (except by using a query string, or matrix
parameters, which we
don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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.
I don't think doing 3 is a good idea right now and this new concept
needs to be discussed more.
1 looks easier to implements and write but 2 is probably more
consistent with what we have today (plus it adds the feature of
listing the nested spaces of some space) so I'm more for 2.
[1]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
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),
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
> 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,
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]
> >>
> >>
>
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
> >> [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
> solution
> >> >>> 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
> "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):
> >> >>>
> >>
>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
> >> >>>
> >> >>> 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"
> 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 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;:
> >> >>>
> >> >>>> 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
> >:
> >> >>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>>
> >> >>>>> 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
>> >>>>
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> 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
--
Thomas Mortagne
_______________________________________________
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
6:38 p.m.
On 6 Jul 2015 at 18:14:07, Guillaume Louis-Marie Delhumeau
(gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) wrote:
Thomas actually convinced me that 2) is better.
It’s certainly “better” for the implementer since it’s simpler to implement.
In the end it’s really a question of:
1) shorter URLs or not (since escaping “pages” is not really a big deal - FTR I had
replied to you
at http://jira.xwiki.org/browse/XWIKI-12206?focusedCommentId=87131&page=co…)131).
2) Whether we want to strictly consider each space as a REST entity or the list of spaces
itself as the REST entity, i.e. in the same way as our EntityReference in Java or not.
<much thinking…/>
I think I agree that sol2 is the best (for now), even though I hate that it’s so long, but
it’s consistent.
Thanks
-Vincent
PS: Re 1) see
http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-u…
which says that if we want to be fine we should not go beyond 2000 chars in URLs (IE10 has
a 2083 limit for example - Incidentally this could also be a problem for the view action
for long hierarchies but your hierarchies would really need to be very long: with an
average of 20 chars per space level, you’d need an 80 -level deep hierarchy to reach the
problem - And a 40 level deep one for the REST URL). So we should be safe.
Why: how to access a space called "pages"?
It would be:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/
But this url has an other meaning: list all pages of the space
Europe.France.Paris
I have proposed to escape the space name for this kind of use-case, like
this:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/~pages/
But this escaping using "~" is not very RESTful (it would be a custom,
xwiki-specific, standard).
Meanwhile the solution 2 does not have this drawback:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/
is very clear. We have nothing to escape.
Thanks,
2015-07-06 17:43 GMT+02:00 Guillaume "Louis-Marie" Delhumeau <
gdelhumeau(a)xwiki.com>gt;:
> Note: I am personally for 1).
>
> 2015-07-06 17:38 GMT+02:00 Thomas Mortagne :
>
>> On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau
>> wrote:
>> > Let me resume everything.
>> >
>> > It seems that jax-rs does not have a solution for handling list
>> parameters
>> > [1] (except by using a query string, or matrix parameters, which we
>> don't
>> > want). But, thanks to some hacks (example there:
>> >
>>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
>> )
>> > 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:
>> >
>> /xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
>> > - 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.
>>
>> I don't think doing 3 is a good idea right now and this new concept
>> needs to be discussed more.
>>
>> 1 looks easier to implements and write but 2 is probably more
>> consistent with what we have today (plus it adds the feature of
>> listing the nested spaces of some space) so I'm more for 2.
>>
>> >
>> > [1]
>> >
>>
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
>> >
>> > Thanks,
>> > Guillaume
[snip]
7 Jul
7 Jul
9:03 a.m.
On 6 Jul 2015 at 18:38:02, vincent(a)massol.net
(vincent@massol.net(mailto:vincent@massol.net)) wrote:
On 6 Jul 2015 at 18:14:07, Guillaume Louis-Marie Delhumeau
(gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) wrote:
Forget that sentence. I was tired yesterday and mixed up things apparently :)
-Vincent
Thomas actually convinced me that 2) is better.
It’s certainly “better” for the implementer since it’s simpler to implement. In the end it’s really a question of:
1) shorter URLs or not (since escaping “pages” is not really a big deal - FTR I had
replied to you at
http://jira.xwiki.org/browse/XWIKI-12206?focusedCommentId=87131&page=co…)131).
2) Whether we want to strictly consider each space as a REST entity or the list of spaces
itself as the REST entity, i.e. in the same way as our EntityReference in Java or not.
I think I agree that sol2 is the best (for now), even though I hate that it’s so long,
but it’s consistent.
Thanks
-Vincent
PS: Re 1) see
http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-u…
which says that if we want to be fine we should not go beyond 2000 chars in URLs (IE10 has
a 2083 limit for example - Incidentally this could also be a problem for the view action
for long hierarchies but your hierarchies would really need to be very long: with an
average of 20 chars per space level, you’d need an 80 -level deep hierarchy to reach the
problem - And a 40 level deep one for the REST URL). So we should be safe.
Why: how to access a space called
"pages"?
It would be:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/
But this url has an other meaning: list all pages of the space
Europe.France.Paris
I have proposed to escape the space name for this kind of use-case, like
this:
/xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/~pages/
But this escaping using "~" is not very RESTful (it would be a custom,
xwiki-specific, standard).
Meanwhile the solution 2 does not have this drawback:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/
is very clear. We have nothing to escape.
Thanks,
2015-07-06 17:43 GMT+02:00 Guillaume "Louis-Marie" Delhumeau <
gdelhumeau(a)xwiki.com>gt;:
> Note: I am personally for 1).
>
> 2015-07-06 17:38 GMT+02:00 Thomas Mortagne :
>
>> On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau
>> wrote:
>> > Let me resume everything.
>> >
>> > It seems that jax-rs does not have a solution for handling list
>> parameters
>> > [1] (except by using a query string, or matrix parameters, which we
>> don't
>> > want). But, thanks to some hacks (example there:
>> >
>>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
>> )
>> > 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:
>> >
>> /xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
>> > - 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.
>>
>> I don't think doing 3 is a good idea right now and this new concept
>> needs to be discussed more.
>>
>> 1 looks easier to implements and write but 2 is probably more
>> consistent with what we have today (plus it adds the feature of
>> listing the nested spaces of some space) so I'm more for 2.
>>
>> >
>> > [1]
>> >
>>
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
>> >
>> > Thanks,
>> > Guillaume
[snip]
2:04 p.m.
+1 for solution 2 (multiple /spaces/)
Thanks,
Marius
On Mon, Jul 6, 2015 at 6:38 PM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume
"Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
Let me resume everything.
It seems that jax-rs does not have a solution for handling list parameters
[1] (except by using a query string, or matrix parameters, which we don't
want). But, thanks to some hacks (example there:
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…)
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:
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
- 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.
I don't think doing 3 is a good idea right now and this new concept
needs to be discussed more.
1 looks easier to implements and write but 2 is probably more
consistent with what we have today (plus it adds the feature of
listing the nested spaces of some space) so I'm more for 2.
[1]
http://cxf.547215.n5.nabble.com/Passing-array-as-a-parameter-in-JAX-RS-td56…
Thanks,
Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <thomas.mortagne(a)xwiki.com>om>:
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs On Mon, Jul 6, 2015 at 3:51 PM, Guillaume
"Louis-Marie" Delhumeau
<gdelhumeau(a)xwiki.com> wrote:
--
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 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), 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
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, 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]
>
>
http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensio…
> [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
solution
> >>> 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
"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):
> >>>
>
https://github.com/xwiki/xwiki-platform/compare/d5f4997ddf40d70c8eef9a9ee0e…
> >>>
> >>> 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"
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 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;:
> >>>
> >>>> 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
:
> >>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>> 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
> >>>>
> >>>
> >>>
> >>>
> >>> --
> >>> 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
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
3 Jul
3 Jul
11:50 a.m.
It seems that the solution of Eduard is possible to implement (of
course, have to check if restlet is doing it or if we have to change
framework).
http://www.nakov.com/blog/2009/07/15/jax-rs-path-pathparam-and-optional-par…
On 03/07/2015 11:20, Fabio Mancinelli 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 <enygma2002(a)gmail.com> wrote:
--
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
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 <vincent(a)massol.net>
wrote:
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
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:
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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
--
Guillaume Delhumeau (guillaume.delhumeau(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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
3412
days inactive
3417
days old
24 comments
7 participants
participants (7)
-
Eduard Moraru -
Fabio Mancinelli -
Guillaume "Louis-Marie" Delhumeau -
Jean SIMARD -
Marius Dumitru Florea -
Thomas Mortagne -
vincent＠massol.net