[xwiki-devs] Fwd: [Proposal] Having dots as spaces separator in the REST api to handle nested spaces
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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
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 <[email protected]> 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- 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 ([email protected](mailto:[email protected])) 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
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, [email protected] <[email protected]> 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 ( [email protected](mailto:[email protected])) 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
+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 <[email protected]> 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, [email protected] <[email protected]> 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 ( [email protected](mailto:[email protected])) 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
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 <[email protected]> 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, [email protected] <[email protected]> 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 ( [email protected](mailto:[email protected])) 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
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=com.atl...) 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 ([email protected](mailto:[email protected])) 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, [email protected] 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 ( [email protected](mailto:[email protected])) 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
On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto:[email protected])) 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=com.atl...)
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 ([email protected](mailto:[email protected])) 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, [email protected] 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 ( [email protected](mailto:[email protected])) 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
I am currently trying to implement the multiple spaces proposal to see if it is doable. 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>: > > > > > > On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto: > [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137 > ) > > > > 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 ([email protected] > (mailto:[email protected])) 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, [email protected] > > > > 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 ( > > > >> [email protected](mailto:[email protected])) 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 > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
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/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c
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 <
[email protected]>:
> I am currently trying to implement the multiple spaces proposal to see if
> it is doable.
>
> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>:
>
>>
>>
>>
>>
>>
>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto:
>> [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137
>> )
>> >
>> > 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 ([email protected]
>> (mailto:[email protected])) 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, [email protected]
>> > > > 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 (
>> > > >> [email protected](mailto:[email protected])) 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
>> [email protected]
>> http://lists.xwiki.org/mailman/listinfo/devs
>>
>
>
>
> --
> Guillaume Delhumeau ([email protected])
> Research & Development Engineer at XWiki SAS
> Committer on the XWiki.org project
>
--
Guillaume Delhumeau ([email protected])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
>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/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c
>
> 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 <
> [email protected]>:
>
>> I am currently trying to implement the multiple spaces proposal to see if
>> it is doable.
>>
>> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>:
>>
>>>
>>>
>>>
>>>
>>>
>>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto:
>>> [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137
>>> )
>>>>
>>>> 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 ([email protected]
>>> (mailto:[email protected])) 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, [email protected]
>>>>>> 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 (
>>>>>>> [email protected](mailto:[email protected])) 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
>>> [email protected]
>>> http://lists.xwiki.org/mailman/listinfo/devs
>>>
>>
>>
>>
>> --
>> Guillaume Delhumeau ([email protected])
>> Research & Development Engineer at XWiki SAS
>> Committer on the XWiki.org project
>>
>
>
>
--
Jean Simard
[email protected]
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. On Mon, Jul 6, 2015 at 1:26 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c > > 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 < > [email protected]>: > >> I am currently trying to implement the multiple spaces proposal to see if >> it is doable. >> >> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>: >> >>> >>> >>> >>> >>> >>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto: >>> [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137 >>> ) >>> > >>> > 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 ([email protected] >>> (mailto:[email protected])) 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, [email protected] >>> > > > 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 ( >>> > > >> [email protected](mailto:[email protected])) 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 >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >> >> >> >> -- >> Guillaume Delhumeau ([email protected]) >> Research & Development Engineer at XWiki SAS >> Committer on the XWiki.org project >> > > > > -- > Guillaume Delhumeau ([email protected]) > Research & Development Engineer at XWiki SAS > Committer on the XWiki.org project > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs -- Thomas Mortagne
On Mon, Jul 6, 2015 at 1:57 PM, Thomas Mortagne <[email protected]> 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 > <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c >> >> 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 < >> [email protected]>: >> >>> I am currently trying to implement the multiple spaces proposal to see if >>> it is doable. >>> >>> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>: >>> >>>> >>>> >>>> >>>> >>>> >>>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto: >>>> [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137 >>>> ) >>>> > >>>> > 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 ([email protected] >>>> (mailto:[email protected])) 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, [email protected] >>>> > > > 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 ( >>>> > > >> [email protected](mailto:[email protected])) 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 >>>> [email protected] >>>> http://lists.xwiki.org/mailman/listinfo/devs >>>> >>> >>> >>> >>> -- >>> Guillaume Delhumeau ([email protected]) >>> Research & Development Engineer at XWiki SAS >>> Committer on the XWiki.org project >>> >> >> >> >> -- >> Guillaume Delhumeau ([email protected]) >> Research & Development Engineer at XWiki SAS >> Committer on the XWiki.org project >> _______________________________________________ >> devs mailing list >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs > > > > -- > Thomas Mortagne -- 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/extensions/jaxrs [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 > <[email protected]> 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 >> <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9e98d767eb586...26b63f99654c90ba39c0601ee0d7c9397e1c629c >>> >>> 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 < >>> [email protected]>: >>> >>>> I am currently trying to implement the multiple spaces proposal to see if >>>> it is doable. >>>> >>>> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>: >>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected](mailto: >>>>> [email protected])) 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=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-87137 >>>>> ) >>>>>> >>>>>> 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 ([email protected] >>>>> (mailto:[email protected])) 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, [email protected] >>>>>>>> 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 ( >>>>>>>>> [email protected](mailto:[email protected])) 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 >>>>> [email protected] >>>>> http://lists.xwiki.org/mailman/listinfo/devs >>>>> >>>> >>>> >>>> >>>> -- >>>> Guillaume Delhumeau ([email protected]) >>>> Research & Development Engineer at XWiki SAS >>>> Committer on the XWiki.org project >>>> >>> >>> >>> >>> -- >>> Guillaume Delhumeau ([email protected]) >>> Research & Development Engineer at XWiki SAS >>> Committer on the XWiki.org project >>> _______________________________________________ >>> devs mailing list >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >> >> >> >> -- >> Thomas Mortagne > > > -- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org
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 <[email protected]>:
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/extension... [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 <[email protected]> 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 <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
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 < [email protected]>:
I am currently trying to implement the multiple spaces proposal to
see if
it is doable.
2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>:
On 3 Jul 2015 at 11:48:24, [email protected] ([email protected]
(mailto:
[email protected])) 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=com.atl...
) > > 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 ( [email protected] (mailto:[email protected])) 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, [email protected] >>> 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 ( >>>> [email protected](mailto:[email protected])) 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 [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension... [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 <[email protected]> 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 <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
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 < [email protected]>:
I am currently trying to implement the multiple spaces proposal to
see if
it is doable.
2015-07-03 11:52 GMT+02:00 [email protected] <[email protected]>:
> > > > > > On 3 Jul 2015 at 11:48:24, [email protected] ([email protected] (mailto: > [email protected])) 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=com.atl... > ) >> >> 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 ( [email protected] > (mailto:[email protected])) 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, [email protected] >>>> 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 ( >>>>> [email protected](mailto:[email protected])) 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 > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs >
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
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/d5f4997ddf40d70c8eef9a9ee0e9...) 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-td563... Thanks, Guillaume 2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension...
[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 <[email protected]> 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 <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
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 < [email protected]>:
> I am currently trying to implement the multiple spaces proposal to see if > it is doable. > > 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected] : > >> >> >> >> >> >> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected] (mailto: >> [email protected])) 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=com.atl...
>> ) >>> >>> 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 ( [email protected] >> (mailto:[email protected])) 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, [email protected] >>>>> 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 ( >>>>>> [email protected](mailto:[email protected])) 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 >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs >> > > > > -- > Guillaume Delhumeau ([email protected]) > Research & Development Engineer at XWiki SAS > Committer on the XWiki.org project >
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
Hi, On 6 Jul 2015 at 17:12:11, Guillaume Louis-Marie Delhumeau ([email protected](mailto:[email protected])) 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/d5f4997ddf40d70c8eef9a9ee0e9...) 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/d5f4997ddf40d70c8eef9a9ee0e9... vs https://github.com/xwiki/xwiki-platform/commit/3e83b6cf44e8#diff-3d532b9e955... ) 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-td563...
Thanks, Guillaume
[snip]
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...) 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-td563...
Thanks, Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension...
[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 <[email protected]> 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 <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
> > 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 < > [email protected]>: > >> I am currently trying to implement the multiple spaces proposal to see if >> it is doable. >> >> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected] : >> >>> >>> >>> >>> >>> >>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected] (mailto: >>> [email protected])) 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=com.atl...
>>> ) >>>> >>>> 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 ( [email protected] >>> (mailto:[email protected])) 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, [email protected] >>>>>> 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 ( >>>>>>> [email protected](mailto:[email protected])) 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 >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >> >> >> >> -- >> Guillaume Delhumeau ([email protected]) >> Research & Development Engineer at XWiki SAS >> Committer on the XWiki.org project >> > > > > -- > Guillaume Delhumeau ([email protected]) > Research & Development Engineer at XWiki SAS > Committer on the XWiki.org project > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
Note: I am personally for 1). 2015-07-06 17:38 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9... )
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-td563...
Thanks, Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension...
[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 <[email protected]> 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 > <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
>> >> 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 < >> [email protected]>: >> >>> I am currently trying to implement the multiple spaces proposal to see if >>> it is doable. >>> >>> 2015-07-03 11:52 GMT+02:00 [email protected] < [email protected] : >>> >>>> >>>> >>>> >>>> >>>> >>>> On 3 Jul 2015 at 11:48:24, [email protected] ( [email protected] (mailto: >>>> [email protected])) 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=com.atl...
>>>> ) >>>>> >>>>> 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 ( [email protected] >>>> (mailto:[email protected])) 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, [email protected] >>>>>>> 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 ( >>>>>>>> [email protected](mailto:[email protected])) 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 >>>> [email protected] >>>> http://lists.xwiki.org/mailman/listinfo/devs >>>> >>> >>> >>> >>> -- >>> Guillaume Delhumeau ([email protected]) >>> Research & Development Engineer at XWiki SAS >>> Committer on the XWiki.org project >>> >> >> >> >> -- >> Guillaume Delhumeau ([email protected]) >> Research & Development Engineer at XWiki SAS >> Committer on the XWiki.org project >> _______________________________________________ >> devs mailing list >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs > > > > -- > Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
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 < [email protected]>:
Note: I am personally for 1).
2015-07-06 17:38 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9... )
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-td563...
Thanks, Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension...
[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 > <[email protected]> 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 >> <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
>>> >>> 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 < >>> [email protected]>: >>> >>>> I am currently trying to implement the multiple spaces proposal to see if >>>> it is doable. >>>> >>>> 2015-07-03 11:52 GMT+02:00 [email protected] < [email protected] : >>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> On 3 Jul 2015 at 11:48:24, [email protected] ( [email protected] (mailto: >>>>> [email protected])) 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=com.atl...
>>>>> ) >>>>>> >>>>>> 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 ( [email protected] >>>>> (mailto:[email protected])) 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, [email protected] >>>>>>>> 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 ( >>>>>>>>> [email protected](mailto:[email protected])) 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 >>>>> [email protected] >>>>> http://lists.xwiki.org/mailman/listinfo/devs >>>>> >>>> >>>> >>>> >>>> -- >>>> Guillaume Delhumeau ([email protected]) >>>> Research & Development Engineer at XWiki SAS >>>> Committer on the XWiki.org project >>>> >>> >>> >>> >>> -- >>> Guillaume Delhumeau ([email protected]) >>> Research & Development Engineer at XWiki SAS >>> Committer on the XWiki.org project >>> _______________________________________________ >>> devs mailing list >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >> >> >> >> -- >> Thomas Mortagne > > >
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
On 6 Jul 2015 at 18:14:07, Guillaume Louis-Marie Delhumeau ([email protected](mailto:[email protected])) 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=com.atl...). 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-ur... 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 < [email protected]>:
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/d5f4997ddf40d70c8eef9a9ee0e9... )
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-td563...
Thanks, Guillaume
[snip]
On 6 Jul 2015 at 18:38:02, [email protected] ([email protected](mailto:[email protected])) wrote:
On 6 Jul 2015 at 18:14:07, Guillaume Louis-Marie Delhumeau ([email protected](mailto:[email protected])) wrote:
Thomas actually convinced me that 2) is better.
It’s certainly “better” for the implementer since it’s simpler to implement.
Forget that sentence. I was tired yesterday and mixed up things apparently :) -Vincent
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=com.atl...). 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-ur... 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 < [email protected]>:
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/d5f4997ddf40d70c8eef9a9ee0e9... )
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-td563...
Thanks, Guillaume
[snip]
+1 for solution 2 (multiple /spaces/) Thanks, Marius On Mon, Jul 6, 2015 at 6:38 PM, Thomas Mortagne <[email protected]> wrote:
On Mon, Jul 6, 2015 at 5:11 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...) 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-td563...
Thanks, Guillaume
2015-07-06 16:02 GMT+02:00 Thomas Mortagne <[email protected]>:
On Mon, Jul 6, 2015 at 3:51 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> 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 <[email protected]>:
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/extension...
[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 <[email protected]> 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 > <[email protected]> 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/d5f4997ddf40d70c8eef9a9ee0e9...
>> >> 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 < >> [email protected]>: >> >>> I am currently trying to implement the multiple spaces proposal to see if >>> it is doable. >>> >>> 2015-07-03 11:52 GMT+02:00 [email protected] <[email protected] : >>> >>>> >>>> >>>> >>>> >>>> >>>> On 3 Jul 2015 at 11:48:24, [email protected] ([email protected] (mailto: >>>> [email protected])) 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=com.atl...
>>>> ) >>>>> >>>>> 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 ( [email protected] >>>> (mailto:[email protected])) 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, [email protected] >>>>>>> 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 ( >>>>>>>> [email protected](mailto:[email protected])) 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 >>>> [email protected] >>>> http://lists.xwiki.org/mailman/listinfo/devs >>>> >>> >>> >>> >>> -- >>> Guillaume Delhumeau ([email protected]) >>> Research & Development Engineer at XWiki SAS >>> Committer on the XWiki.org project >>> >> >> >> >> -- >> Guillaume Delhumeau ([email protected]) >> Research & Development Engineer at XWiki SAS >> Committer on the XWiki.org project >> _______________________________________________ >> devs mailing list >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs > > > > -- > Thomas Mortagne
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
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-para... 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 <[email protected]> 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, [email protected] <[email protected]> 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 ( [email protected](mailto:[email protected])) 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 ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Jean Simard [email protected] Research engineer at XWiki SAS http://www.xwiki.com Committer on the XWiki.org project http://www.xwiki.org
participants (7)
-
Eduard Moraru -
Fabio Mancinelli -
Guillaume "Louis-Marie" Delhumeau -
Jean SIMARD -
Marius Dumitru Florea -
Thomas Mortagne -
vincent＠massol.net